GUIDE

Understanding the Client-first style and naming system

This page will help you become familiar with the Client-first system so you and your team can easily scale your site.

Every website is different and unique to each client. Client-first is not a set of strict rules—rather, it is designed to be flexible and customizable according to your needs.

Think of this as a thought process to help build a clean, organized Webflow project.

This system is built for Webflow Designer organization and use. This system was implemented to more easily onboard those that are beginners or have no website experience.

Understanding the naming convention

Think about naming classes as what they do and their purpose

The Client-first system uses prefixes and keywords for organization and easy search-ability. This system has these main purposes:

1. Help view and use global classes in the Webflow styles panel. The 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 design on the page is, without looking at any visual.

Searching for classes in the styles panel

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.

When you start typing class name keywords in the styles panel of Webflow Designer, a list of all related classes appear as a suggestion for the typed class. This makes it easy to see the list of styles you can apply to a web element.

If you type the max- or margin- prefix for example and you'll see all the available styles for that class. Your website has the following predefined classes:

page- container- max- margin- padding- hide- show- text-

They all have values applied to them, and you are free to change those values as you like.

Components

You will most likely build components in your site—related web elements that are grouped together to represent a larger parent element. For example a team member component may have an image, name, and title.

This is not to be confused with Webflow symbols, although you can turn a component into a reusable symbol.

In the Client-first naming system, to label a component, we add an underscore to the end of the name of the parent element. For example team-member-card_. This lets everyone identify that this is a component. And within that parent element are the other related elements. We prefix those with with component name followed by the name of the element.
team-member-card_
team-member-card_profile-image
team-member-card_member-name
team-member-card_title

Sections

For organizing main sections on your page, we like to label them as section-[section-name]. This class shouldn't need any styling applied to it, but you may if you wish. This lets you easily see the organization of your site in the Navigator.

Creating custom classes

Creating custom classes is recommended for inner page elements and inevitable. We want to keep global, core page elements such as margins and padding strictly for page structure, and take advantage of custom classes for inner page content.

For example, if you use pricing-background-color, we can understand that this class is used for adjusting the background color of the pricing section.

Avoid acronyms, abbreviations, and directional names. For example headshot-align-c-r does not tell us where that headshot is or what is actually being done to the headshot element. This may be on several pages without knowing, and any new team member or developer comes in and reads this will not have any context or know what it means.

The worst thing you can do to your site is have Webflow auto-name classes for you: Div block 1, Container 5, Text block 30. These will be everyone's worst nightmare and will be impossible to scale the site or build new pages without affecting other ones.

Naming CMS collection lists

Collection-List-Wrapper - This parent element does not need to have classes and styles applied to it.

Collection-List - Label this with clear keywords followed by -list. You can add any styles you want to this.

Collection-Item - Label this with clear keywords followed by -item. You can add any styles you want to this.

Global vs add-on vs combo classes

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 the style of the class will update your entire site globally! This can be very powerful and can help you build pages faster.

Margin-bottom, Padding-vertical are examples of global classes.

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.

padding-small is a global class, and on its own, adds a small amount of padding to all four sides of an element. But when you add it on top of padding-vertical, you're only adding the padding in the vertical direction.

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.

Let's say for example you have a button class and you want to create a variation of it. So you create the class version-secondary on top and then add styles.

What this will mean is that any changes made to button version-secondary will only apply to elements that contain both classes. In other words, the button class will not be affected.

However, the reverse is true! Changes made to whichever is the first listed class, in this case, button, will affect all elements with the button class.

Further explanation of global add-on vs combo classes

Global add-on class

heading-xlarge  hide-mobile-landscape
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.

Often times 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. The hide-mobile-landscape or hide-mobile-portrait class is seen throughout the site to hide desktop-only elements.

You can use hide-mobile-portrait on 100 different elements throughout the website and there is only 1 class that manages that functionality on the css stylesheet, hide-mobile-portrait

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 inherit, 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. But maybe the legal disclaimer text requires a unique font color and weight for example.

More reasons a combo class makes sense in this instance.

Those small changes are not a significant 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 inherit 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 forget 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 combo classes 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 padding-vertical padding-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 editing or 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.

The recommended solution?

It is recommended to add 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 can hold styles such as border, radius, background, and height, justify left, alight right, etc.

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.

Don't overstack classes OR global classes

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.

The solution for overgrouping classes: combo classes + div layering

If you need to apply 6 different styles to an element, consider making it a custom class from the get-go, or separating classes into new parent-child divs.

For example lets say you have a hero section that you apply the following styles to:
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.

The 3 global add-ons can be styled all in one custom class entirely, to become:
section-layer-default hero-card

From here, you can nest that under a parent div and apply global margins or padding to it and you will be able to update padding spacing without affecting section-layer-default

Much more manageable and quick to edit!
padding-vertical
container
section-layer-default hero-card

Why it's not a good idea to add number values to 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.
padding-vertical
container
section-layer-default hero-card

Structure and the 4pt system

We defined the core basics so you can build pages more easily

Below you'll see the common practice to structuring web pages.

This site uses the 4pt system, which is a common web standard. Multiples of 4 are set as values for everything—font sizes, margin values, padding values, etc.

This can be changed at anytime when required by your build. It is recommended to default to the 4pt system if the spacing system hasn't already been defined otherwise.

For example, you could set text-small to a value of 12pt, text-medium  to a value of 16pt and text-large to a value of 28pt. In some instances, rem units may be used over pt, as it is makes the website more accessible.

Core page structure

With structure, you want to work from the outside in. Use global utility classes such as page-wrapper, margin and padding to structure the majority of your pages.

Refrain from adding styles and creating combo classes to global classes.
page-wrapper
section-[section-name]
page-padding
container-medium
...inside the container is your content: headlines, text, images, buttons, etc. and these can start to turn into custom classes.

page-wrapper

Acts as the outer most parent of all elements on the page, and is optional.


Primary use case:

  1. You can quickly 'copy all elements on a page' that will be pasted to a different page.
  2. This is a global class that you can style to an entire page without styling the Body tag.

section-[section-name]

Styling the section div is optional.

Primary use case is to identify a section on a page from the Navigator panel.

It's best to see descriptive words describing the section so you can quickly navigate through the page through the Navigator panel.

For example,

A homepage may have sections like header, about, how it works, testimonials, contact. You may name your section classes like this:
page-wrapper
section-home-header
section-home-about
section-home-services
section-home-team
section-home-contact

page-padding

This adds padding only to the left and right.

Primary use case is to create global horizontal spacing site-wide. This class is specifically for the outermost spacing of the left and right of the site. It's not for spacing inside elements.

With one reserved class that manages horizontal spacing, you can make powerful global updates to padding site-wide on all device viewports.

Recommended structure looks like this:
page-wrapper
section-[section-name]
page-padding
container-medium
...inside the container is your content: headlines, text, images, buttons, etc.

Spacing

Spacing system that keeps vertical and horizontal spacing global on your website.

Margin
We like to use margin for spacing between elements and components.

Global use of margin direction:
margin-vertical margin-horizontal margin-top margin-bottom margin-left margin-right

Each of these classes are available in different sizes and you will also find classes for tablet and mobile views.
margin-xxsmall
Desktop
4px | 0.25rem
Tablet
4px | 0.25rem
Mobile landscape
4px | 0.25rem
Mobile portrait
4px | 0.25rem
margin-xsmall
Desktop
8px | 0.5rem
Tablet
8px | 0.5rem
Mobile landscape
8px | 0.5rem
Mobile portrait
8px | 0.5rem
margin-small
Desktop
16px | 1rem
Tablet
16px | 1rem
Mobile landscape
16px | 1rem
Mobile portrait
16px | 1rem
margin-medium
Desktop
32px | 2rem
Tablet
24px | 1.55rem
Mobile landscape
20px | 1.25rem
Mobile portrait
20px | 1.25rem
margin-large
Desktop
48px | 3rem
Tablet
40px | 2.5rem
Mobile landscape
24px | 1.5rem
Mobile portrait
24px | 1.5rem
margin-xlarge
Desktop
64px | 4rem
Tablet
48px | 3rem
Mobile landscape
32px | 2rem
Mobile portrait
32px | 2rem
margin-xxlarge
Desktop
80px | 5rem
Tablet
64px | 4rem
Mobile landscape
48px | 3rem
Mobile portrait
48px | 3rem
margin-huge
Desktop
96px | 6rem
Tablet
80px | 5rem
Mobile landscape
56px | 3.5rem
Mobile portrait
56px | 3.5rem
Padding
We like to use padding for creating space within sections and containers.

Global use of padding direction:
padding-vertical padding-horizontal padding-top padding-bottom padding-left padding-right

Each of these classes are available in different sizes and you will also find classes for tablet and mobile views.
padding-xxsmall
Desktop
4px | 0.25rem
Tablet
4px | 0.25rem
Mobile landscape
4px | 0.25rem
Mobile portrait
4px | 0.25rem
padding-xsmall
Desktop
8px | 0.5rem
Tablet
8px | 0.5rem
Mobile landscape
8px | 0.5rem
Mobile portrait
8px | 0.5rem
padding-small
Desktop
16px | 1rem
Tablet
16px | 1rem
Mobile landscape
16px | 1rem
Mobile portrait
16px | 1rem
padding-medium
Desktop
32px | 2rem
Tablet
24px | 1.55rem
Mobile landscape
20px | 1.25rem
Mobile portrait
20px | 1.25rem
padding-large
Desktop
48px | 3rem
Tablet
40px | 2.5rem
Mobile landscape
24px | 1.5rem
Mobile portrait
24px | 1.5rem
padding-xlarge
Desktop
64px | 4rem
Tablet
48px | 3rem
Mobile landscape
32px | 2rem
Mobile portrait
32px | 2rem
padding-xxlarge
Desktop
80px | 5rem
Tablet
64px | 4rem
Mobile landscape
48px | 3rem
Mobile portrait
48px | 3rem
padding-huge
Desktop
96px | 6rem
Tablet
80px | 5rem
Mobile landscape
56px | 3.5rem
Mobile portrait
56px | 3.5rem

Remove all spacing

Sets margins and paddings to 0. Useful for removing native Webflow component spacing.

spacing-clean

Typography

Follow this system to keep your typography styles professional and easy to organize

Below you'll see the common practice to structuring web pages.

You can use the heading- global class to style headings, and the text- prefix to add customizations to your text.

Heading and paragraph tags

Always use the HTML tag to define default heading and paragraph styles.
It is recommended to keep your Headings class-free except when you have a very specific or uniquely styled Heading. HTML tag styling is the recommended way to apply any and all styles to your default Heading and paragraph text.

If you do not understand how to edit the HTML tags, watch this quick lesson.

For SEO purposes, it is recommended to have only one H1 per page, which is usually the very top headline of the page. All subsequent headings should be H2, H3, H4, etc.

Styling text

Always use the HTML tag to define default headings styles.
heading-xlarge - 64pt (4rem)
heading-large - 48pt (3rem)
heading-medium - 32pt (2rem)
text-large - 24pt (1.5rem)
text-small - 16pt (1rem)
text-tiny - 12pt (.75rem)

Rich text

The rich text element allows you to create and format headings, paragraphs, blockquotes, images, and video all in one place instead of having to add and format them individually.

The text-rich-text class will hold the default styles for the rich text element. Limit your custom class rich text classes. Each time you make one, it's a new class you have to update when you want to change typography styles globally.

h1

h2

h3

h4

h5
h6
block quote

inline text link

  • list item
  • list item

Regular paragraph text

Responsive visibility: hide and show elements by screen size

Hide classes to set display:none

hide is a global class that can hide an element on all views. You will also find tablet, landscape, and mobile versions.
hide-mobile-landscape for example will hide an element on mobile landscape and below.
hide-mobile-portrait for example will hide an element on mobile portrait and below.
hide-tablet for example will hide an element on tablet and below.
show is a global class that show an element on all views. You will also find tablet, landscape, and mobile versions.
show-mobile-landscape for example is a global class that show an element starting from mobile landscape and up.
show-mobile-portrait for example is a global class that show an element starting from mobile portrait and up.
show-tablet for example is a global class that show an element starting from tablet and up.

Icons

Icon classes

icon-xsmall
icon-small
icon-medium
icon-large
icon-xlarge

Utility classes

Special add-ons to bring unique components to your site.

This is more specific to developers and those that have more technical Webflow and CSS knowledge.
z-1 - Bring an element closer on the z-index. Sets z-index to 1.
z-2 - Bring an element closer on the z-index. Sets z-index to 2.
align-center - Centers a container on max-xxx the screen. Sets margin left and right to auto.
div-square - Creates and maintains a 1:1 dimension of a div. CSS magic.
layer - Add to div to make it expand the entire size of the parent element. Make sure the parent div has 'position: relative'.
clickable-off - Prevents all click and hover interaction with an element. Sets pointer-events to none.
clickable-on - Enables all click and hover interaction with an element. Sets pointer-events to auto.

Questions?

Send a message to support@cartandcraft.studio