Migrating from Client-First to Lumos: The Complete Guide for Webflow Developers

Why Switch from Client-First to Lumos?

Lumos delivers three core advantages over Client-First: breakpointless responsive design, automatic theming through CSS variable cascading, and significantly leaner CSS on larger projects.

Client-First is still an excellent framework for small to medium projects. Its strength is simplicity: readable class names, thorough documentation, quick onboarding. But Webflow has evolved a lot since Client-First was created. Native variables, variable modes, components, container queries: Lumos leverages all of them, while Client-First hasn't received a major update since January 2024.

When we migrated our builds to Lumos at Klyra, the first thing we noticed was the reduction in custom classes. In Client-First, every slightly specific CSS property needs a dedicated class. With Lumos, the stacked utility system (one component class + one utility class) and global variables cut the stylesheet down considerably.

On a 15+ page project, the difference is striking. Client-First tends to accumulate custom classes and extra HTML layers (page-padding, section-padding, etc.) that weigh down the code as the site grows. Lumos centralizes everything in variables: you change one value, it propagates everywhere.

The other factor is accessibility. Lumos is designed from the ground up so that layouts adapt when a user increases their preferred font size. Webflow's px-based breakpoints don't react to browser zoom. Lumos techniques (flexbox wrapping, autofit grids, rem units) solve this natively.

HTML Structure: section_ and page-padding vs u-section and u-container

The structural difference between the two frameworks shows up in the very first section.

Client-First:

<section class="section_hero">
 <div class="page-padding">
   <div class="container-large">
     <div class="padding-vertical padding-xxlarge">
       <div class="hero_component">
         <!-- content -->
       </div>
     </div>
   </div>
 </div>
</section>


Lumos:

<section class="hero_wrap u-section">
 <div class="hero_contain u-container">
   <div class="hero_layout">
     <!-- content -->
   </div>
 </div>
</section>


In Client-First, you stack structural divs: page-padding for horizontal margins, container-large for max-width, padding-vertical for vertical spacing. In Lumos, all of that is handled by two utility classes: u-section manages vertical padding and background colors, u-container handles max-width, side margins, and container-type: inline-size.

The critical rule to remember: never put display: grid or grid-template-columns on u-container. Because u-container has container-type: inline-size, it serves as the container query context. If you put a grid on it, no container query can override it. Layout always goes on a child _layout div:

/* CORRECT */
.hero_layout {
 display: var(--flex-medium, grid);
 flex-direction: column;
 grid-template-columns: repeat(12, minmax(0, 1fr));
}

/* WRONG: breaks container queries */
.hero_contain {
 display: grid;
 grid-template-columns: repeat(12, minmax(0, 1fr));
}


What Is Lumos's Class Naming System Compared to Client-First?

Lumos uses underscores to separate class name parts, caps depth at 3 underscores maximum, and requires a u- prefix for all utility classes. Client-First uses hyphens and has no mandatory prefix.

Here's the direct mapping:

ConceptClient-FirstLumosSeparatorHyphen (hero-header_title)Underscore (hero_title)Heading_heading_titleParagraph_paragraph_textImage_image_imgMandatory wrapperNoYes (_wrap for every component/subcomponent)UtilitiesNo prefix (text-size-large)u- prefix (u-text-style-large)Combo classes.is-large, .is-dark.is-reversed, .is-1, .is-activeMax depthNo strict limit3 underscores max

In Client-First, you might write home-hero_content-wrapper_heading. In Lumos, that becomes hero_content_title. If you go beyond 3 underscores, you start a new subcomponent with _wrap.

The key point: every HTML element in Lumos needs a component class. No bare <div> with only a utility class. The structure is always: component class first, then stacked utility. For example: <h2 class="hero_title u-text-style-h2">.

Multi-word parts keep their hyphens: hero_link_wrap, not hero_link-wrap. Underscores separate component levels, hyphens join words within the same level.

How Does Breakpointless Responsive Design Work in Lumos?

Lumos eliminates Webflow breakpoints by using responsive CSS variables that automatically flip between values based on container size. Zero @media queries: the browser decides when the layout should change.

This is the biggest mental shift coming from Client-First. In CF, you style desktop, then adjust on tablet, mobile landscape, mobile portrait. Four breakpoints, four passes in the designer.

Lumos does the opposite. You style once on desktop, and responsiveness is handled by:

1. Native CSS techniques. Automatic flexbox wrapping, autofit/autofill grids, and flex-basis make most layouts adapt to smaller screens naturally.

2. Responsive variables. Lumos provides variables like --flex-medium, --column-medium, --none-small that change value based on screen size. You use them as CSS fallbacks:

/* Switches from grid to flex at medium screens and below */
display: var(--flex-medium, grid);

/* Switches from row to column */
flex-direction: var(--column-medium, row);


The variables --_responsive---large, --_responsive---medium, --_responsive---small, and --_responsive---xsmall equal 1 or 0 depending on the active breakpoint. You can combine them in calc() for fine-tuned adjustments:

grid-template-columns: repeat(
 calc(
   var(--_responsive---large) * 4 +
   var(--_responsive---medium) * 3 +
   var(--_responsive---small) * 2 +
   var(--_responsive---xsmall) * 1
 ),
 minmax(0, 1fr)
);


3. Container queries as a last resort. If responsive variables aren't enough (e.g., reordering complex elements), you use @container:

@container (width < 50em) {
 .hero_layout {
   display: flex;
 }
}


The major benefit: when a user zooms in their browser or increases their preferred font size, the layout adapts. With Webflow's px breakpoints, text overflows. With Lumos, content stays readable.

Theming and Colors: Lumos's Automatic Cascade

Client-First handles colors with manual variables. You create your color variables in Webflow, apply them element by element, and if you want a dark section, you override each color by hand.

Lumos works through cascading. You apply u-theme-dark to a section, and all color variables update automatically: backgrounds, text, borders, buttons, links. No need to touch the children.

<!-- Light section (default) -->
<section class="about_wrap u-section u-theme-light">
 <!-- Everything automatically uses light colors -->
</section>

<!-- Dark section -->
<section class="features_wrap u-section u-theme-dark">
 <!-- Everything switches to dark colors -->
</section>

<!-- Brand section -->
<section class="cta_wrap u-section u-theme-brand">
 <!-- Brand colors applied everywhere -->
</section>


Theme variables follow a consistent convention: --_theme---background, --_theme---text, --_theme---border, --_theme---heading-accent. For buttons: --_theme---button-primary--background, --_theme---button-primary--text, and so on.

This system makes dark mode easy. With Lumos, recoloring an entire section or page is as simple as changing a class name or attribute. It also makes scroll-based color transitions (like a navbar that matches the theme of whichever section is in view) much simpler to implement.

In Client-First, you'd need to create variants of each component for each color mode, or stack override classes. With Lumos, the cascade does the work.

How Does the Trigger/State System Work in Lumos?

Lumos's trigger/state system replaces CSS descendant selectors with CSS variables that flip between 0 and 1. Children react by reading the variable, without ever targeting a parent or state in their selector.

In Client-First (or vanilla CSS), to change a text color on button hover, you'd write:

/* Classic approach with descendant selector */
.button:hover .button_text {
 color: white;
}


In Lumos, you never target a state in the selector. You add data-trigger="hover focus" to the interactive element, and children read the --_trigger---on and --_trigger---off variables:

.hero_button {
 background-color: color-mix(
   in hsl,
   var(--_theme---button-primary--background) calc(100% * var(--_trigger---on)),
   var(--_theme---button-primary--background-hover) calc(100% * var(--_trigger---off))
 );
 transition: all 300ms;
}


At rest, --_trigger---on equals 1 and --_trigger---off equals 0. On hover, they flip. The color-mix() interpolates between the two values.

For states (active tabs, open accordions), it's the same principle with --_state---true / --_state---false:

/* Opacity changes based on active state */
.tabs_link_text {
 opacity: var(--_state---false);
}

/* Underline bar scales based on state */
.tabs_link_bar {
 transform: scaleY(calc(var(--_state---false)));
 transition: transform 300ms;
}


The golden rule: true/on always comes first, false/off second in your expressions. And never, ever use .is-active or [data-state] in a CSS selector. You only read variable values.

5 Mistakes Every Client-First Developer Makes with Lumos

After guiding several migrations at Klyra, here are the most common pitfalls.

1. Putting a grid on u-container. This is the number one reflex. In Client-First, you put your layout directly in the container. In Lumos, the container has container-type: inline-size: layout must go on a child _layout div.

2. Using @media queries instead of responsive variables. If you're writing @media (max-width: 768px), you're doing Client-First inside Lumos. Use display: var(--flex-medium, grid) and flex-direction: var(--column-medium, row).

3. Using px instead of rem. Lumos bans px everywhere (except border-width, which uses the --border-width--main variable). Text max-width uses ch. Breakpoints in @container use em. Everything else is rem.

4. Putting false/off before true/on in expressions. In a color-mix() or calc(), the order is always true/on first. If you reverse it, values won't match the expected states.

5. Writing descendant selectors. In Client-First, .nav_link.w--current .nav_link_text is normal. In Lumos, it's forbidden. You use data-state="current" on the parent and .nav_link_text { opacity: var(--_state---false); } on the child.

Conclusion

Migrating from Client-First to Lumos is an investment that pays back quickly. Breakpointless responsive speeds up every build. Cascading themes eliminate duplicates. The trigger/state system keeps CSS cleaner and more maintainable.

The learning curve is real, especially the first two weeks. But once you've internalized the patterns (responsive variables, trigger/state, section/container/layout structure), you won't want to go back.

The Webflow ecosystem is clearly moving toward more variables, more components, more container queries. Lumos aligns with that direction. Client-First remains relevant for smaller projects or junior teams, but for complex, scalable builds, Lumos is the right call.

Need help with your Lumos migration? At Klyra, a studio specializing in Lumos, it's what we do best.

Frequently Asked Questions

Should you migrate an existing Client-First site to Lumos?

Not necessarily. If your Client-First site works well and doesn't need significant evolution, the migration won't deliver enough value to justify the time invested. However, if you're planning a redesign or major scaling, that's the right moment to start the new build on Lumos from scratch.

Is Lumos suitable for projects where the client edits the site themselves?

Lumos is more technical than Client-First for non-developer clients. Class names are less descriptive, and the variable system requires a basic understanding of CSS. For projects where the client regularly works in the Designer, Client-First often remains the better choice. For developer-managed projects, Lumos takes the lead.

How long does it take to learn Lumos when coming from Client-First?

Expect about two to three weeks of intensive practice to get comfortable with the core concepts (responsive variables, trigger/state, naming conventions). Your first full project will take roughly 30% longer than usual. By the second project, you'll start building faster than you did in Client-First on complex builds.

Can you mix Client-First and Lumos elements in the same project?

Technically yes, but it's not recommended. The naming conventions, spacing system, and responsive approach are fundamentally different. Mixing them will create confusion for any developer who picks up the project later. Choose one framework and stick with it for the entire build.

Does Lumos work with Webflow components and the CMS?

Yes, and it's actually one of its strengths. Lumos's component-based approach is designed to integrate with Webflow's native components. The CMS works normally with Lumos classes. Variable modes even let you switch a CMS component's theme based on its display context.

<script type="application/ld+json">
{
 "@context": "https://schema.org",
 "@type": "FAQPage",
 "mainEntity": [
   {
     "@type": "Question",
     "name": "Should you migrate an existing Client-First site to Lumos?",
     "acceptedAnswer": {
       "@type": "Answer",
       "text": "Not necessarily. If your Client-First site works well and doesn't need significant evolution, the migration won't deliver enough value to justify the time invested. However, if you're planning a redesign or major scaling, that's the right moment to start the new build on Lumos from scratch."
     }
   },
   {
     "@type": "Question",
     "name": "Is Lumos suitable for projects where the client edits the site themselves?",
     "acceptedAnswer": {
       "@type": "Answer",
       "text": "Lumos is more technical than Client-First for non-developer clients. Class names are less descriptive, and the variable system requires a basic understanding of CSS. For projects where the client regularly works in the Designer, Client-First often remains the better choice. For developer-managed projects, Lumos takes the lead."
     }
   },
   {
     "@type": "Question",
     "name": "How long does it take to learn Lumos when coming from Client-First?",
     "acceptedAnswer": {
       "@type": "Answer",
       "text": "Expect about two to three weeks of intensive practice to get comfortable with the core concepts (responsive variables, trigger/state, naming conventions). Your first full project will take roughly 30% longer than usual. By the second project, you'll start building faster than you did in Client-First on complex builds."
     }
   },
   {
     "@type": "Question",
     "name": "Can you mix Client-First and Lumos elements in the same project?",
     "acceptedAnswer": {
       "@type": "Answer",
       "text": "Technically yes, but it's not recommended. The naming conventions, spacing system, and responsive approach are fundamentally different. Mixing them will create confusion for any developer who picks up the project later. Choose one framework and stick with it for the entire build."
     }
   },
   {
     "@type": "Question",
     "name": "Does Lumos work with Webflow components and the CMS?",
     "acceptedAnswer": {
       "@type": "Answer",
       "text": "Yes, and it's actually one of its strengths. Lumos's component-based approach is designed to integrate with Webflow's native components. The CMS works normally with Lumos classes. Variable modes even let you switch a CMS component's theme based on its display context."
     }
   }
 ]
}
</script>