Naming Convention docs read to you

Don't want to read? In this video, we explain everything to you.

Why Client-first?

Client-first is a set of guidelines and strategies to help you build Webflow websites in a clear and scalable way that any human can understand.

We think clients, marketers, other Webflow developers, and anyone in-between should be able to read a class name and understand what that class is responsible for styling.

These are not strict rules. Every build is different. Client-first is designed to be flexible and customizable for any build.

Client-first is a thought process to help create a clean and organized Webflow project. It helps us think about how and why we name classes.

This is not following every best practice of traditional HTML and CSS build convention. Good. This isn't traditional, this is Webflow. This system is built for Webflow Designer organization and use. This system is built to more easily onboard our clients to their new marketing-friendly Webflow website.
Video walkthrough

Sitemap

Meaningful class namesPre-written classes in Client-firstCustom class creationKeywordsGlobals and combosDon't over-stack classesComing soon

Our naming convention is 'meaningful class names'

Class names should say what they do. When creating a name for a class think to yourself,

"What is this class doing?"

"What is its purpose?"

"Why does it exist?"

"How can I give the most context into what this class is responsible for?"

The answer to these questions should be represented in the name of class.

This is a core deep concept of Client-first. Every class name should serve a meaningful purpose.

When you are naming classes, describe what that class is doing. Why does it exist? Give the client as much context into what the purpose of the class and its relationship to the website.

A Webflow developer, client, or marketer should be able to understand what the class is doing based on a class name, even if they're never heard of Client-first before.

Use prefixes and keywords

'Client-first' naming convention uses prefixes and keywords for organization. Our system can help you in creating meaningful class names for the elements throughout the website build.

There are three core reasons for this strategy:

1. Prefixes help us view and use our global classes in the Webflow styles panel. Our prefix and keyword system can be seen as a smart search for available classes.

2. Identify and understand what a class' core responsibility is in the build. We use keywords to understand what the element is or what it's doing. We should have enough context from the class name that we know its impact on the site.

3. Organization and human readability in Navigator. You should be able to read a Navigator html tree and understand what the visual on the page is, without seeing any visual.

1. Searching in styles panel of Designer

When we start typing class names in the styles panel of Webflow Designer, a list of classes appear as a suggestion for our typed class. Ease of class search optimizations are seen throughout Client-first.

If we want to find a class that sets a max-width, we will likely want to use a global class for this. We can keep all of our max-width related classes under the same class prefix, max-. We are using the word 'max' as our prefix keyword for max-width. Typing 'max' in the styles panel will return all of our classes that refer to max-width, for example global max-width classes that are used throughout the website. max-small  max-medium  max-large  max-xlarge
‍
In addition to using style names to identify a class, we may want to identify a class based on a component or element on the page. When we create components in our Webflow project, for example a testimonial slider, the component name serves as our prefix keyword. When classes are created for a visible element on the site, we can use that element as a keyword in the class name. This will help clients and developers a clear indication of what this class is responsible for.

For example, we may create a "testimonial slider" component in our project. We will give the testimonial slider, as well as all of the elements inside of the testimonial slider, a prefix of testimonial-slider_ . When we type 'testimonial-slider' in the Styles panel, we can view all custom classes related to our testimonial slider. Any element inside the component that needs a custom class specific to that component should use the component name prefix. We can then identify this class as being responsible for custom styles in the "testimonial slider".

Let's continue to more explanation.

2. Identify and understand what a class is responsible for in the build

A strong keyword gives you context into what this class/element is doing. Being as descriptive as possible in your naming will help you stay organized.

Let's look at the "testimonial slider" example from above.

testimonial-slider_ is telling us that this is a custom class created and used for our testimonial slider. The prefix identifies the component or element that it is being influenced by this class. When we see the class testimonial-slider_headshot-wrapper , we know that this class is created specifically for a headshot wrapper inside of our testimonial slider component. We get a lot of context around what this class is used for on our website.

Inside our testimonial we may have a headshot, a piece of text, and a line that we created with a div. All three elements need to have styles applied to them and the styles are unique to the testimonial slider. We can name each one so we understand what the class is being used for - and where is the site I'm using it.

We will name these classes so the person looking at them knows exactly what it's for
‍
testimonial-slider_headshot-image

testimonial-slider_company-text

testimonial-slider_divider line


It's your job, the developer, to name your classes so they give the most amount of context while staying organized and meaningful in your build.

Is this class being created to manage a specific style? Is this class being created to stylize a specific element?

As you continue reviewing and understanding this documentation, you will better understand how to give meaningful names to your classes.

3. Understand your page from the Navigator panel

Navigator is a crucial tool in Webflow Designer. You need to access it and navigate it as you're working in Webflow.

Our goal is for someone unfamiliar with your website to know what's happening on the page based on reading through the navigator panel.

We have a div layer in our html that is specifically used for easier section navigation in navigator.

section-[section-name]  is a naming convention we use in Client-first to help us quickly navigate through sections. Click the div, scroll to the section. This has a 'anchor scrolling' type effect for your page in Designer.

Classes pre-written in Client-first cloneable

Client-first build comes with classes and styles that help you get started with any Webflow project. We give you styles that that help you establish a strong page structure - or achieve a common style add-on.

These classes are not specific to any website, design, style, or layout. They are global classes that manage one or few core styles that many pages, sections, or elements need.

Some pre-written classes allow you to make powerful global changes to elements throughout the build. For example, universal horizontal padding or universal vertical element spacing. Some classes are for improved workflow, like classes that apply display:none.

Here are some prefixes of classes that are included with the client-first build
‍
page- container- max- margin- padding- hide- show- text-

Our core outer page structures can be built with these pre-written classes.
‍
page-wrapper
‍section-[section-identifer]
‍page-padding
‍container
...(e.g. components, elements, etc.)
Layers of the outer page structure can be removed or rearranged based on your page layout
‍
- page-padding is optional

- You can use additional container outside of page-padding

- section-[section-identifier] has a primary goal of identifying a section inside Navigator. This is not meant to have styles on it. However, it can have styles applied to it if it makes sense for your build. This works really well as a base class for common global add-ons for sections, like padding-vertical-large and background-blue!
Use margin- classes to establish vertical space inside and outside of your page elements. Using margin- classes will help keep your vertical spacing global throughout your build.
margin-bottom-xsmall
margin-bottom-small
margin-bottom-medium
It's very important to know that all pre-written styles inside Client-first are optional. If your build requires you to organize spacing in a different way, or use a unique structure for outer page structure, you may do it. Client-first helps you stay organized and deliver clean Webflow builds. If your build needs to do something different to stay organized, do it. Staying organized and clear in our project is our goal.

Creating unique custom classes for your build

It's recommended! Not everything can fit in a global system - and usually it should not fit into a global system. If you lock yourself into a global system, changes are more difficult and the learning curve on your website increases. Global class use should be used when styles need to be managed on a global level. If there's no reason to update the class on a global level, or it doesn't speed up your build process, then it shouldn't be global. It should be custom!

Creating custom classes is encouraged for inner page elements. There are many benefits to creating a custom class, even if a global class system can be used. The biggest advantage is the ease and speed of updates. Custom classes can help in lowering the learning curve for your build. Custom classes with human readable words can help someone who is inexperienced with Webflow better understand your Webflow build.

If I see the class services-item-background-texture, I know what that class is created for and what its primary purpose is, to manage styles for “a texture that’s on a background image of a services item.” When I make a change to the styles on the class, I can be sure that they will be including this element on the page.

We may be able to create the same end result with 3 stacked classes. For example, background-absolute  opacity-low  texture-1. When combined, these three classes give us the same outcome as services-item-background-texture. In traditional CSS convention, this would be seen as a win. We do not add to our CSS file and we can control everything globally with these classes.


Here’s why we don’t do this in Webflow

You increase the learning curve.
If a knowledgeable dev visits your site, they should understand these stacked classes are giving the element shared styles from the three classes. And a beginner Webflow developer may not know this. Your client probably doesn’t know this. It’s going to be more difficult for them to update this elements style. Forbid… a… new combo class styling based on 3 stacked global classes. This becomes an unorganized mess. Giving custom classes will allow your clients to play with Designer styles panel with minimal damage.
‍
Inability to reorder styles in Designer styles panel
How terrible is it when you have to swap or remove a class that is first in the list of a multi-class combo styling. This is a bad workflow and an inherent issue with Webflow UX. Using custom classes will limit this happening in your workflow. Instead of digging through a long combo, use the power of Webflow’s fast CSS styling UX.
‍
Writing CSS in Webflow is fast
It’s understandable that traditional CSS frowns upon new class creation. It takes time to hand write styles to a CSS style sheet. And the code would be managed by a developer. Global classes make sense. Now we’re in Webflow. Writing CSS is fast and efficient through the styles panel. Take advantage of it. Creating a new class and applying styles is usually less time consuming than figuring out and maintaining a deep global class system.
‍
Who cares about a tiny CSS savings?
What’s the real difference in load time between a 52kb CSS file vs. a 59kb CSS file? Is it worth making your site less accessible and scalable?

Don't be afraid to use custom classes

... as long as they're organized. Always use clear, meaningful words when naming your custom classes.

Use component naming when you can. Use prefixes for organization and search. Be descriptive of the element.

Sometimes these components can be reused on different pages. Their name can be more general, like list-3-col_component. This type of class can be used throughout the build. It's not specific as to the section it is being used for. Since 'list' is a common keyword in our system, we can assume this is a reusable class that creates a 3 column list.

Sometimes components are specific to one page. Their name can be more specific, like .pricing-calc_component. Now we can organize our classes inside our pricing-calc. For example, pricing-calc_add-button, pricing-calc_display-value, pricing-calc_cta-email

Using component naming helps us understand that a set of elements come together to create a custom UI element. Together they are all creating a visual style for the component.

.[components]_

Components are defined as a group of page elements that create a complete ui element. For example, a newsletter signup, team grid, pricing calculator, reusable 3 column grid, or a clients list.

When a class is specific to a component, we use a [component]_ prefix followed by an underscore. The component keyword and underscore tells us the class style is specific to a recurring component that can be used site-wide.

What is a component? Components are defined as a group of page elements that create a complete ui element. This component may or may not be built into the symbol system of Designer.
‍
Sometimes these components can be reused on different pages. Their name can be more general, like list-3-col_component. Inside this is component, we find elements such as, list-3-col_title list-3-col_hover-icon and list-3-col_background-layer. These type of classes can be used throughout the build. It's not specific as to the content section it is being used for or the page it's on. It can be reused elsewhere on the site without confusion.

Sometimes components are specific to one page. Their name can be more specific, like pricing-calc_component. Now we can organize our classes inside our pricing-calc. For example, pricing-calc_add-button pricing-calc_display-value pricing-calc_cta-email

Using component naming helps us understand that a set of elements come together to create a custom UI element. If a client wants to create a new page, they can use the Client-first outer page structure + components to build it.

Use [component-name]_component as the outer/master div holding the entire component. Repeat the component name and underscore prefix for each element inside.
The nav menu seen on every page
nav_component
nav_logo-flex
nav_links-wrapper
nav_cta-primary
A recurring testimonial slider
testimonial-slider_component
testimonial-slider_name
testimonial-slider_headshot-wrapper
testimonial-slider_headshot-layer
The newsletter signup bar before the footer
newsletter-form_component
newsletter-form_field-wrapper
newsletter-form_input
newsletter-form_submit-trigger
The team grid list seen on About and Careers pages
jobs_component
jobs_name
jobs_title
jobs_location
The team grid list seen on About and Careers pages
team-grid_component
team-grid_name
team-grid_title
team-grid_headshot
The horizontal logo bar seen scattered throughout the build
clients-bar_component
clients-bar_logo-row
clients-bar_logo
clients-bar_rotation-trigger

When these items can be reused throughout the site, create a Webflow Symbol for this component so clients can easily make updates to the component with override fields. Only create a symbol for elements that will be recurring in multiple instances throughout the build.

.[element]-  or  .[style]-

Not everything is a component. There are some elements that are truly unique or relate to something more specific that is not within a component.

When a class is specific to an element or style, we use an [element]- or [style]-  prefix. Note that the only difference is the underscore and the dash. Our classes that are not specific to a component will get a dash after the prefix keyword.

Here we see elements on the page that are not components. We use our best judgement to name them so we can give as much context about it. Below are two examples.
Form elements that are seen throughout the build and are not inside a single recurring form component.
form-radio-label
form-submit
form-input-row
Shapes and accents in the headers of the website.
header-shapes-wrapper
header-shapes-texture-layer
header-shape-1
header-shape-2

We may want to create a global class for each common background color seen on the website. Every section either has default white, black, blue, or gray. We use the background-  prefix so we can search for our background color options in the styles panel.
Background color css style that should remain global by class.
background-black
background-gray
background-blue

There are no hard strict rules with Client-first. Use your best judgement and make decisions that will be clear for others viewing your project. Your site may require a different set of prefixes and globals. Client-first helps you organize your site for your project.

Using keywords in class names

Be specific in naming

When creating new styles in your project, be specific when naming them. Class names, add-ons, and combos should be named in a way that gives the client the most context into what that class is doing. If a class name or group of class names is read, the reader should have as much information as they can about what the class' purpose is.

Keywords go from general to specific within a class name

Let's look at margin-top-small as an example.
‍
The most general keyword is 'margin'. This is telling us that this class has to do with spacing an element. This is the primary and the most powerful keyword that defines the class name.

'top' is getting more specific and telling us where that space is being applied. It's telling us this is vertical spacing applied to the top of the element.

'small' tells us the size of the spacing that is applied to the top. This is the most specific keyword that relates to the spacing applied to the element.

With this logic, we can see all of our 'margin' classes by typing margin. This can be a long list of all available margin spacing classes. Further typing 'top' can give us the available options for spacing we can apply to the top. In the search panel, this returns 'margin-top' - 'small' , 'medium' , 'large' . We navigate through our global classes by following our keyword convention.
Let's look at team_quote-headshot as an example.
‍
The prefix is team_, which tells us this element is a "Team" component. This structure is a reusable component that can be used elsewhere on the site. We can view classes created for this Team component by typing our "Team" prefix into the styles panel.

'quote' is getting more specific and telling us this is in the quote section. We may have several parts of this quote. In the styles panel, typing 'quote' will return all of the classes that were created for the quote of the team component.

'headshot' is getting even more specific and telling us that this is the headshot element within the quote section that is inside our team component.

Reading the class name team_quote-headshot is clear and logical that any person, even if they don't understand the CSS behind it, would understand that editing this will do [something] to an element on that page that is related to the team quote headshot. That's a great hint for the inexperienced viewer.

The bad way:
‍
If this class was named headshot-align-center , then we have no information where or what that headshot is. We have a useless note to the developer that display:flex right was applied. Who cares. We want to know what this headshot class is for visually by reading it.

If this class was named flex-align-c-r  we have no information where or what this is for on the page and a client has no idea what this means. We have a useless note to the developer that there is something with flex and with it being aligned center with something on the right. Who cares. We want to know what this headshot class is for visually by reading it.

Forbid an auto class naming of Image45. Our worst nightmare. We must always prevent auto naming. That's one reason we recommend creating custom classes for elements that are visible on the page. It will allow your clients and beginner developers to more freely make changes throughout the website without creating auto named classes. Instead, they can make the style updates to a page element that is clearly named.

Commonly used keywords and reusing keywords

Use the same commonly used keywords so your build stays organized as you create custom classes. Standardize your keywords as much as possible so you can share builds with developers using the 'Client-first' system. Formalizing keywords like 'list', 'item', 'container', 'wrapper', etc. will help us stay organized.
'page' - Prefix to refer to a core page style that influences elements page-wide.
Use page-wrapper to define the outermost 'wrapper' for our page.
Use page-padding to define global left/right padding for all of our pages.
'section' - Keyword used to define an entire section of content.
Use section-[identifier] to visually identify a section in Navigator.
'container' - Keyword for core page content width.
Use container as a class that 'contains' items within a certain maximum width and centers the container on the page.
It's recommend this keyword stays reserved for this use only. Use 'wrapper' as a keyword for containing inner page elements.
'wrapper' - Keyword for wrapping or containing elements on a page. Wrapper is used for structure and non-content items.
Use wrapper to create a parent element that holds children elements. For example, if you need to have an image and a piece of text inside the same div, use the 'wrapper' keyword to define that div parent element. For example, 'profile-info-wrapper'.
'list' - Used for a div that is surrounding a grid or group of items. List is used for content items.
Use the list keyword for a grouping of items. If you have 10 people on your "Leadership" page, the div surrounding those items is the list.
'item' - Used for an item within a list.
Use the item keyword for an item within a list. If you have 10 people on your "Leadership" page, each person would be an item.
'layer' - Used for an element that is above or below other elements on the page.
Use for accents behind images, page textures, background graphic elements, etc. A layer is not something the user interacts with. It is a supporting graphic element for visual purposes.
'margin' - Used for spacing elements from each other on the page.
Applies margin-top or margin-bottom styles to elements to space them from one another.
'padding' - Used for adding equal inner space to sections.
Applies padding-top/bottom or padding-left/right to elements.

How to name and use Webflow dynamic lists

Dynamic List Wrapper = - Do not use the dynamic list wrapper for styles or naming. There is no reason to add a class to it. Our child Dynamic List can manage all of the class stylings we need for any layout.
Dyanmic List = .[clear-keywords]-list - Add any styles you want
Dynamic Item = .[clear-keywords]-item  - Add any styles you want

Using global classes, global add-on classes, and combo classes

We've been talking a lot about global classes, global add-on classes, and combo classes. Now let's understand what these are and how understanding them can make our builds more powerful. Understanding this concept takes your Webflow styles game to the next level.

What is a global class?

A global class is a class that is universal in the build. It is not specific to one specific element. This class can be applied to any element in the build and the styles will be applied to that element. This is commonly used for spacing, padding, sizes, and colors.

Changing a global class should be simple, powerful, and meaningful.

There are two reasons to create global classes in your build:
‍

1. One style change to the class will update the class globally across the website.
‍
A global class should be meaningful in that it holds the key to an important core style that can be managed on a global level. These are css style values that may be changed.

For example, global management of vertical element spacing, left-right padding, max width values, and typography.

Let's look at a vertical element spacing example. margin-bottom-large has a margin-bottom of 60px. If you want spacing reduced across the entire website, you can update margin-bottom-large to 40px in one style change. This change will be seen site-wide everywhere margin-bottom-large is applied. You have just globally changed the large spacing value everywhere on the website.

An example of a style that should not be global is a class called position-absolute that adds position: absolute to an element. There is no reason to change the styles on this class. What will you change position-absolute to? There is no meaningful reason to update this class on a global level. This type of css style can be added to a custom class.


2. Faster build time, commonly used useful styles, client convenience.
‍
You may want to use a css style as a global class to help you build faster and smarter. For example, hide-mobile or show-mobile. This will allow us to selectively change the visibility of elements throughout the website. Rather than applying custom classes that only manage mobile visibility, we can use these global classes that manage popular visibility rules.

Remember that it is not necessary to do anything. Your build may not have the need for any style-based global add-ons.

What is a global add-on class?

A global add-on class is a global class. It is an 'add-on' if it is added to an element in addition to other classes. It can be added to other classes on the website to add a style to an element.

For example, we have the container global class and it serves the purpose of creating the initial container structure. It gives you the option to define a default max-width to your container. If you have a default max-width you can add max width to the container class.

If there are different max-widths, and you want to keep them organized and global, you can use global add-on classes to manage your site's max-width.

This Style System comes with pre-written global max-width classes max-xsmall max-small max-medium max-large max-xlarge max-xxlarge . The max-width values for each max- class can be customized for your build.

max-small can be added in addition to container to add a new style to the element. We get the base core styles of container + a custom the max-width property for that section.

max-small is a global class, which means it can be applied to any element on the site. It is not specific to use with containers. We can add max-small to a paragraph, title, or any element on our site. That element will have the max-width property without the unneeded base structure from container.


Why we don't use style value numbers in our class names. If you add max-128 as an add-on class to elements across your site, and then need to change the css property to 'max-width: 32px', you would also want to change the class name to max-132 . This class change will not be seen site-wide. The add-on classes you added max-128 to will not change along with the base class rename. Your site will now have a dead max-128 class across your website with no styles applied to it. This is a serious Webflow problem that can become very time consuming to fix if you need to change class names. This is why we use small, medium, large.

We can change the max-small class' max-width value and do not have to worry about re-aligning the class name. It's 'small', not specific to a value. This will allow the class to stay truly global.
‍

What is a combo class?

A combo class is created as a variant to a base class. A combo class is used when there is a variation that needs to be added to a class that already exists.

The key difference between a global add-on and a combo is that a combo is creating a new class styling on the css stylesheet and the global add-on is not creating a new class styling on the css stylesheet.

For example, we have button class to define the primary button on the website. Most buttons on the site have only this class. However, there are some variations to this button like 'alternate' and 'reverse'

All buttons take the base styles from the button class and need additional styles applied to it to achieve the unique button style.

Our alternate button has a different background-color and text color.

Our reverse button has a reverse flex style to move the arrow icon to the other side of the button.

We don't want to create alternate and reverse as global classes. Their style rules use is specific to creating a variation of our button. We aren't going to use them separately and we aren't going to apply them to other classes. This is a perfect use case for a creating a new combo class.

button will set the core styles. Important styles that we would want to manage globally throughout all buttons, such as padding, font size, or font weight. We want to keep those styles in one manageable class, our button class. We do not want to add them again to a new class like button-reverse. If we have to update the padding of the button, we have to do it in two places. If we forgot to update the other, then we start the terrible cycle of a mismatched style website.

Instead, we create a combo class! button reverse. This creates a brand new style on your style sheet that creates a style for the classes used together as a pair, or a combo! The styles of reverse are applied on top of the styles of the button. We inherent the important globally manageable styles of our button, like padding, font size, or font weight, and add our our special variation of reverse, which applies background-color and font size on top of the padding, font size, or font weight styles.

Making a change to our button class will also update all of our button reverse.

POWERFUL!

More explanation of global add-on vs. combo

Global add-on class

heading-xlarge  hide-mobile
Both of these are global classes. They are not specific to one unique element. Each one of these classes can be applied to any element on the website. When applied to any element, their styles will be applied.
‍
Oftentimes global classes are created for commonly used styles on the site.
‍
In this example, when these classes are applied together, they give text a larger size and hide that larger text at the mobile responsive level. Each can be used separately, but in this case they can be used together without creating a custom class.
‍
You can now toggle mobile visibility of this piece of text without creating a new class. Our hide-mobile class is seen throughout the site to hide desktop-only elements.
‍
You can use hide-mobile on 30 different elements throughout the website and there is only 1 class that manages that functionality on the css stylesheet, hide-mobile

Combo class

text-small  legal-disclaimer
Above text-small is our base class. .legal-disclaimer is a combo class to text-small that creates a style specific to legal disclaimer text.
‍
The ‘legal disclaimer’ text is for one or several instances of text that applies a unique style on top of the styles of our small text. Small text is seen throughout the site so we have a global class for it, text-small. 
‍
Instead of creating a global system for the ‘legal disclaimer’ text, we will create a new combo class instead. 
‍
We don’t need to use the legal-disclaimer class on its own.

We don’t want to re-write our important core styles that are applied to our small text.
‍
This is an ideal use for a combo class.
‍
The combo class will allow us to use, or inherent, styles from our global .text-small class and apply our new unique legal-disclaimer styles on top of it. For example, we may want to inherent letter-spacing, and font size. These are important styles that are seen everywhere in our small text throughout the site. The legal text requires a unique font color. Additionally, that font color has to change on hover.
‍
More reasons a combo class makes sense in this instance
‍
This is not a large enough change to our text-small to qualify for a full custom class without text-small as the base.
‍
We can update our .text-small styles globally. We inherited letter-spacing, and font size from our .text-small class. This means we can update the styles on this class and it will change our text-small legal-disclaimer. This is important to keep our site styles unified. Imagine there has to be site-wide change to the font-size on the small text on the site. It’s too small and users are reporting they can’t read it. We want to change it from 10px to 12px. Using our proper combo class setup, we can update this value once and it will update globally for all elements that use and inherent the font-size of text-small.

IF we applied a unique custom class for our legal disclaimer class, without the use of text-small, we would have to update the font-size in two places. This becomes very unmanageable as you grow your website. It’s so unmanageable that you may end up only changing it on text-small and forgetting to change font-size for other elements. This leads to an unorganized and mis-matched styled site.
‍
Important to understand:
When creating a combo class, you are creating a brand new piece of css for your stylesheet. If you create 20 variations of text-small as combo classes, you will create 20 new class stylings on the css stylesheet. Make sure that your combo class decisions are meaningful.

Never create combos from global add-ons

Never create a combo class styling from global add-on classes. This defeats our purpose of true global classes and can lead to organization issues as the website scales.
‍
For example, if you create container max-large and decide that this section needs an additional unique style, you should not create a new combo class out of these global add-ons. This means - you should not be adding new styles in the Designer styles panel while these two classes are the only two classes in the styles panel.
‍
For example, if you have a unique section that has border, radius, background, height, etc. This styling should not be a combo class created from our global classes. 
‍
Even if this combination of globals is only seen once on the site, a new combo class styling should not be created for this customization. We want to keep our globals and global add-ons clean and truly global. Their only styles and use should be to provide an important core style that can be changed and managed globally. As we start adding unique stylings, we risk our global system falling apart.
‍
Adding a new class name at the end of the class list is not recommended either. For example, container max-large features-custom  is not recommended. This would create a unique combo class that would require both container and max-large global classes to be present in order for the new features-custom style to be shown. Let’s say this custom features style needs to be used elsewhere. We didn’t plan it on the original build, but 3 months post-build it’s going to be repurposed. The only difference is that the new section needs to be max-medium. Different content, different max-width. If you created a combo in your original features-custom styling, your features-custom combo class would not work with max-medium. features-custom will only work with the exact combination of container and max-large. This is not organized or scalable. It will lead to confusion.
‍
Generally speaking, for most use cases, we never want to add custom classes as combos on top of important global classes on our website. So what do we do?
‍
It is recommended to make this type of unique customization to a different element on the page, or a new HTML layer responsible for this unique style. This will allow for faster edits and updates for others using the website after you. Safely managing a stacked multi-inherited combo style requires more knowledge than a new unique custom class.
‍
We recommend adding an additional parent/child layer in your HTML and have a div that manages this style. For example, creating a class features-custom-layer. This class holds our new border, radius, background, and height styles. This can be placed inside our container element and with position:absolute and top/bottom/left/right:0 to fill the space of the container element, just like it would have if we applied the styling directly to the container.
‍
Understand that these new border, radius, background, and height styles have nothing to do with our styles on container and max-medium. We don’t need to inherit styles from these classes. We need to add these totally different and unique styles to create something visual. This is an ideal scenario for a custom class.

Don't over-stack

It is recommended to create new combo classes for unique page elements instead of stacking globals.

Do not over stack classes.
Do not over stack globals.

1 or 2 classes on an element
Great
‍
3 classes on an element
Ok, but why?
‍
4 classes on an element
Absolute maximum
‍
5 classes on an element
Way too much
Class stacking in Webflow is dangerous. The more you stack, the higher the learning curve for your site. This is a core reason we recommend custom class creation in Client-first.
‍
For example, we may want to add some spacing to our container element. We want to give it margin-top-large to add margin-top to the container max-large class.
‍
Now we have container max-large margin-top-large.
‍
Everything is global and clean! But we’re on the road to heavy class stacking. If this same container needs responsive spacing for tablet and mobile, we can continue adding spacing classes to this container. Now we have container max-large margin-top-large tablet-margin-top-small mobile-margin-top-large.
‍
We have 5 classes on this element. If we have to change this element from max-large to max-xlarge, we have to remove all 3 spacing classes to access and change our max-large class. Now we have to add all 3 classes back and hope that we remembered which 3 were there. This is a terrible Webflow workflow that we don’t want you to experience.

Solution for over grouping classes:
Create a combo styling

If you have a section-layer-default class that is required for base styles of the section layer, but would need 3, 4, 5, or 6+ global classes on top to further customize for this section with global add-ons, consider making this customization a custom class from the beginning.

For example:
section-layer-default background-blue text-gray mobile-reverse

Yes, this is possible, and it will give you what you want. Once we start over-stacking classes, our elements becomes more difficult to manage.

If we need to swap background-blue to background-black, our task is too difficult for developers who want to move fast. We have to remove each class that comes after the background class and swap the background style, then add the removed classes back. If you forget one, you may leave out an important style.

Making this change is now more difficult and time consuming. It requires more of our thinking time. Creating a custom combo class from the beginning will give us more freedom and speed to make changes to this element. If there are further changes to this section, we don't have to worry about how to rearrange our stacked global classes so this works. We can style direct in the styles panel.

Consider moving global add-ons to a new structure on your site. For example,
‍
For example:
‍
section-layer-default style-background-blue style-gray mobile-reverse margin-mobile-medium

Can turn into

section-layer-default home-hero_custom‍
‍
We inherit the important global styles from section-layer-default ; for example, padding, z-index, and transition.

We add our home-hero_custom class as a combo class, which adds background, text color, responsive layout changes, margins to. These class will only work when added in combination to section-layer-default.

This custom combo class gives us more context into what it's there for. It's part of a home-hero component and has other classes nearby that share its purpose, that visually style the home hero!


Here we nest our padding-vertical-large spacing class on a new div inside our section. From there we can add our elements inside the spacing div. We now have two manageable layers - the outer managing background color and mobile responsiveness. The inner managing spacing between elements.
page-wrapper
‍[section-identifer]-section
‍padding-vertical-large
‍container
‍page-padding
...(e.g. grid, layouts, components, etc.)
Styles doing two completely different things are now separated, while remaining global and powerful.

Now our container element is doing what it's supposed to do (contain the content) and our spacing parent div is managing all of the spacing for the container.
‍
This logic can be used throughout the client first. Don’t over-stack. It’s likely that you can layer your HTML or apply your styles to a different element on the page.

Solution for over grouping classes:
Add an additional layer of HTML

When our classes stack too high, we can create a new parent/child HTML 'layer' that specifically manages one or a few important styles that are related to each other. For example, vertical spacing of elements on a page.

Let's look at our base structure for most pages. We have a padding-vertical-large that will separate the section from the section above
page-wrapper
‍[section-identifer]-section
‍padding-vertical-large
‍container
‍page-padding
...(e.g. grid, layouts, components, etc.)
Styles doing two completely different things are now separated, while remaining global and powerful.

We can add all of our margin spacing classes to a div. The container class and max-width add-on is on one div. That div is responsible for managing our content size. The spacing classes on to a new parent div. This dic is responsible for managing the spacing between elements across desktop, tablet and mobile. Two divs with two totally different missions.
‍
Now our container element is doing what it's supposed to do (contain the content) and our spacing parent div is managing all of the spacing for the container. The only reason you would need to edit this div is if you wanted to change the spacing in this section. Viewing the .padding-vertical-large class in the styles panel would show .padding-vertical-large and all of our mobile padding options. We get a single view of the responsive journey for this element. 
‍
This logic can be used throughout the client first. Don’t over-stack. It’s likely that you can layer your HTML or apply your styles to a different element on the page.

Coming soon

We're working on videos, cloneables, UI kits, full builds and feature upgrades to this documentation.

Want something? Let us know.
Please send all feedback to communications@finsweet.com

Questions

ALL comments, suggestions, and notes about this Style System are welcome. Thank you.

Please post all feedback on https://client-first-secret-beta-feedback.webflow.io/