"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
There are three core reasons for this strategy:
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.
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.
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 typography style to a text element, we will likely want to use a global class for this. We can keep all of our text related classes under the same class prefix, text-. When we type 'text' into the styles panel, we will see all of our classes related to our text classes.
We can further use keywords to make our search more powerful. We have different types of text styles. We can style a text element with weight, color, size, and more. Using these secondary keywords will give us more visibility into what's available to us in our class list.
Search text-weight- to return all classes related to text weight. Search text-color- to return all classes related to text color. Search text-size- to return all classes related to text size.
This method for class search can help you stay organized in class naming and encourage you to reuse styles from classes already created. For example, making sure all text-color-blue is styled the same on the site.
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 with 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
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.
Client-first build comes with classes and styles that help you get started with any Webflow project. We give you styles 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 key classes that are included with the Client-first build. This is not a full list of all pre-written classes in Client-first.
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.
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 classes 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. We do not do this in Client-first.
Here's why we don't do stacked classes and prefer to make custom classes:
You increase the learning curve with more global and utility classes.
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
It's a pain 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. Never leave divs blank without a class.
Sometimes we need to use a div in our layout to organize content. Maybe a blank div to hold content for a grid or flex setting. There are many uses to add a div to the page that does not require a class or style.
In Client-first, we always want to add a class to a div, even if it doesn't need styles. If you need to add div in your layout, that means it's playing a purpose. Explain that purpose. Don't make the next person figure it out. Explain what purpose this no-style div is playing in your build.
We recommend creating a custom class without any styles applied to it. Use your component name or keywords that help identify what this element is doing and/or where it is in the build.
For example, a blank div may have a custom class of:
We must give the user as much context into what this div is responsible for. Every element in your build has a purpose.
Without a class there is confusion as to what its purpose is - and we have the risk of Div Block 1 class creation.
What is a component?
Components in Client-first are 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-name]_ prefix followed by an underscore. The underscore tells us the class is specific to a complete ui element in our build.
This component may be unique and have 1 instance in the build. This component may be recurring and have 30 instances. The naming convention stays the same.
We use components in Client-first to organize classes that work together to create a complete ui element.
Many times components are specific to one page or one specific element. Their name can be more specific, like pricing-calc_component. Now we can organize our classes that have been created for the pricing calculator inside our pricing-calc_ component.
The 'add button' needs a custom style. Instead of calling it add-button-custom, we use component name organization. Through component naming, we know this custom add button is related to the pricing calculator pricing-calc_add-button.
Use [component-name]_component as the outer/master div holding the entire component.
For elements inside your component, repeat the component name and underscore prefix and describe what the element is [component-name]_[element-description].
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-large as an example.
The most general keyword is 'margin'. This is telling us that this class has to do with spacing an element. The margin keyword gives us the most context into what this class is responsible for.
'large' tells us the size of the margin. This is more specific as it relates to a type of margin - a margin that is large!
Notice how are not calling this large-margin . Large is more specific than margin. Large as a primary keyword doesn't give us much context into what this class is for.
Let's look at team-list_headshot-wrapper as an example.
The prefix is team-list_, which tells us this element has something to do with the team page or a team section and is a list. We have good context into where this custom class is used.
'headshot' is getting more specific and telling us that this has something to do with the headshot element within team list.
'wrapper' is getting even more specific and telling us this is wrapping the headshot.
Reading the class name team-list_headshot-wrapper is clear and logical, even if the user doesn't understand the CSS behind it. The user would understand that editing this class will do [something] to the headshot. That's a great hint for an inexperienced user.
Now imagine adding more elements inside your headshot wrapper. You may have elements like
'headshot' is still our most general keyword when grouping these elements together. The more descriptive and specific keywords that follow help explain exactly what the element is in relation to the headshot.
Commonly used keywords and reusing keywords
Reuse 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.
Avoid or be careful with these keywords
Avoid these keywords, as they may cause confusion.
How to name and use Webflow dynamic lists
Globals and combos
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 margin, 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 margins, paddings, max width values, and typography.
Let's look at a container class example. container-large has a max-width of 1280px / 80rem. If you want your container max-width reduced across the entire website, you can update container-large to 1200px / 75rem in one style change. This change will be seen site-wide everywhere container-large is applied. You have just globally changed the large container value everywhere on the website.
An example of a style that does not need to be a global class is position-absolute , which adds position: absolute to an element. There is no reason to change the styles on this class globally. 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 is usually required for a specific element, so it can be added as a style on 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 as you're working. Rather than applying custom classes that only manage mobile visibility, we can use these global classes that manage popular visibility rules.
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 features_content class, that contains all the content inside a features component. If we want to limit the width of that class, we always have the option to define max-width directly to the custom class. This is usually recommended.
However, if we want to keep all max-width classes global, and manage max-width on a global scale, we can add a global add-on to the features_content class.
Client-first comes with pre-written global max-width classes max-width-xxsmall , max-width-xsmall , max-width-small , max-width-medium , max-width-large , max-width-xlarge , max-width-xxlarge. The max-width values for each max- class can be customized for your build.
max-width-small can be added in addition to features_content to add a new style to the element. We get the base core styles of features_content + max-width-small adds our global max-width property for that element.
max-width-small is a global class, which means it can be applied to any element on the site. 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 features_content. In this case, max-width-small is acting as a global add-on class.
Why we don't use style value numbers in our class names, especially for global classes:
If you add max-width-128 as an add-on class to elements across your site, and then need to change the css property to 'max-width:132px', you would also want to change the class name to max-width-132 . This class change will not be seen site-wide. The add-on classes you added max-width-128 to will not change along with the base class rename. Your site will now have a dead max-width-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 names like small, medium, large.
We can change the max-width-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.
We use "is" as a combo class prefix to identify that a class is a combo class. When we see is- we know this class is created as a combo class with another class.
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 is-alternate button has a different background-color and text color.
Our is-reverse button has a reverse flex style to move the arrow icon to the other side of the button.
We know from is- that both alternate and reverse classes are being used as a combo.
We don't want to create is-alternate and is-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 + is-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 is-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 is-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 + is-reverse.
More explanation of global add-on vs. combo
Global add-on class
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
We do not use the "is" prefix in global classes or global add-on classes.
Above text-size-small is our base class. is-legal-disclaimer is a combo class to text-size-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-size-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 is-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-size-small class and apply our new unique is-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-size-small to qualify for a full custom class without text-size-small is 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-size-small + is-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 12px to 14px. 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-size-small.
If we applied a unique custom class for our legal disclaimer class, without the use of text-size-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-size-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-size-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 features_content + max-width-small 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. Adding a new style to both classes creates a new combo class.
It is recommended to make this type of unique customization directly to the features_content class. Remove the max-width-small class from the styles panel, apply your styles directly to the features_content custom class, and then reapply the global max-width-small class.
Using this strategy is going to make your builds much more organized and scalable.
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
3 classes on an element
Ok, but why?
4 classes on an element
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-large element. We want to give it margin-top + margin-large to add margin-top to the container-large class.
Now we have container-large + margin-top + margin-large.
Everything is global and clean! But we’re on the road to heavy class stacking. If this same container-large needs responsive spacing for tablet and mobile, we can continue adding spacing classes to this container. Now we have container-large + margin-top + margin-large + is-mobile-small.
We have 4 classes on this element. If we have to change this element from container-large to container-medium, we have to remove all 3 spacing classes to access and change our 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 custom combo class
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 the customization on a unique 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.
section-layer-default + background-blue + text-color-gray + mobile-reverse
Can turn into:
section-layer-default + is-home-header
We inherit the important global styles from section-layer-default ; for example, padding, z-index, and transition.
We add our is-home-header 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 our home-header and likely shares its name with other classes that have the same purpose! To visually style the home header!
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 + padding-large that will separate the section from the section above:
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 div 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.
No layout system
There are zero flex or grid classes that come with Client-first.
Why don't we use a global layout class naming convention?
It increases the learning curve on our website. We don’t want to force anyone to learn our flex or grid system. We don’t want to teach abbreviations or industry-terminology.
For example, we don’t want to see flex-a-l-j-c + flex-mobile-a-c. To someone that doesn't know this layout system, this means nothing. flex? a? j? what is this? You as the developer may know it, but that doesn't mean other developers or your clients will.
We don't want to see col-2-d + col-5-t + col-12m either. Although this convention is more clear, you need to understand how this system works. What do the numbers mean? What do the letters mean? What are columns?
Forbid we have to make a unique customization as a combo class on top of your global system!
flex-a-l-j-c + flex-mobile-a-c + how-it-works-custom. No!
We want our system to be flexible and something anyone can update. We want our website to be something that can be changed. This must be a goal for every client website we build.
Global flex and grid systems require many classes, many add-ons, many globals, and the potential use of unnecessary combo classes. Class stacking is required and the classes that are stacked may not make sense.
This increases the learning curve on your build and most clients are not willing to learn or understand a css layout system. That’s why we aren’t using it.
No matter how simple you think your current favorite layout system is, it's confusing to most clients. It's confusing to most Webflow users! Each layout system is unique and unless someone already knows the layout system, there is a learning curve. Clients want to learn how to use their site, not how css and class stacking works.
Using global layout classes don't give us big benefits. Global layouts usually don't need global updates. Global layout classes do not offer considerable building speed improvements inside Webflow.
We can use the power of global classes if we have recurring grids or flex sections that would benefit from being updated universally. Global layout systems are not against Client-first. If that's what is best for your build, do it.
We do not want to lock everybody into a deep global class layout system for every layout, section, or page of your build. Most sites we build in Webflow do not need a global layout system.
Instead of locking yourself into a global system, create a custom class when you’re designing a new grid or flex element. This will allow your clients, or any new developer, to change layouts by using the styles panel.
Many of our clients go right into Designer and start adjusting styles on classes, even when we instruct them to not do this. After a few weeks, they forget and do it anyway. Why fight it? Let clients use Webflow how clients want to use Webflow.
With custom classes on your layouts, the learning curve for site updates is lower and the likelihood of the client making a big mistake is lower.