KB — Building — Webflow build conventions

Webflow build conventions researched

How we structure, name, and compose every Webflow site — Client-First for the class system, Relume for the component library, and a handful of hard rules that keep projects maintainable after handoff.

Use this when

Starting a new Webflow project, onboarding onto an existing one, or reviewing a build for consistency before handoff.

Definition of done

Every element follows Client-First naming. Relume components are pulled from the library and left structurally intact. CMS collections are named in lowercase with hyphens. All images carry descriptive alt text, interactive elements have accessible labels, and no image exceeds 500 KB before upload. The build passes Webflow's own audit panel clean.

Requirements

  1. Use Finsweet Client-First for all class naming. The system uses a two-part convention — [category]_[name] — where the category is the structural role and the name is specific to the element. A section wrapper becomes section_hero; its inner grid becomes hero_component; a heading inside it becomes hero_heading. Global utility classes (text-style-label, padding-global) are defined once on the Global Styles page and never re-declared. Every class lives in a folder (section_, hero_, button_) to keep the style panel navigable. See the full naming reference for the complete category list.
  2. Follow Client-First structure conventions. Every section gets a three-level stack: section_[name] (full-width container, sets background) → [name]_component (max-width wrapper, sets padding) → [name]_content or the grid/flex layout. Don't skip levels to save elements — the pattern makes sections interchangeable and predictable.
  3. Use Relume as the component starting point. Pull components from the Relume library directly into Webflow. Once pasted, rename every class to Client-First convention before styling — Relume ships with its own class names, which conflict with the category-folder system if left in place. Keep the DOM structure Relume provides; the hierarchy is intentional and accessibility-tested.
  4. Name CMS collections and fields in lowercase with hyphens. Collection slug: blog-posts. Field names: publish-date, author-name. Never use spaces or camelCase — Webflow slugifies inconsistently and the API reflects the raw name. Reference fields should name their target explicitly: category-ref, not category.
  5. Design and style from the base (desktop) breakpoint downward. Webflow cascades styles from the base breakpoint — desktop first, then tablet, then mobile. Set layout and typography at the base breakpoint, then override at smaller breakpoints only where the design genuinely requires it. Never style at a smaller breakpoint before the base is finalized; overrides compound and become hard to untangle.
  6. Apply accessibility requirements at build time, not as a post-launch pass. Every <img> gets a descriptive alt attribute; purely decorative images get an empty alt="". Every interactive element without visible text — icon buttons, close targets, social links — gets an aria-label. Use semantic heading order (h1 → h2 → h3); never skip a level for visual size. Full WCAG requirements are in Accessibility (WCAG).
  7. Optimize assets before uploading. Compress images to WebP or AVIF; target under 200 KB for hero images, under 100 KB for content images. Enable Webflow's built-in lazy loading on any image below the fold. Video backgrounds: host on a CDN and embed via the Video element, not as an asset upload — Webflow's asset store is not a CDN.

Gotchas

Webflow static exports include SRI integrity hashes on their own CSS <link> tags. If you self-host the exported HTML (for staging or a custom server), browsers will reject the stylesheet because the file on your server doesn't match the hash. Strip the integrity and crossorigin attributes from any <link rel="stylesheet"> tags when hosting outside Webflow.

Webflow hosting cannot set arbitrary HTTP response headers. A strict Content-Security-Policy, X-Frame-Options, or other security headers require a proxy in front — typically Cloudflare with a Transform Rule. See Security baseline (CSP/XSS) for the header configuration and the proxy approach.

Client-First utility classes are global by definition — don't override them per-component. If a utility like padding-global needs a different value in one section, create a new component-scoped class instead of tweaking the global. Overriding globals creates invisible coupling that breaks other sections when the global is later updated.

Relume components embed icon SVGs as Webflow Embed elements. Webflow's Designer can't style inside an Embed — set color via CSS custom properties or a wrapper class, not by editing the SVG markup directly. Edits inside the Embed field are easy to lose when Relume updates ship.

Why & sources

Client-First solves the naming chaos that accumulates on Webflow projects when each developer or client makes ad-hoc class names. Folder prefixes make styles scannable; the category-name pattern makes classes predictable across projects. Relume accelerates layout work without sacrificing the naming system because its DOM structure is sound — only the class names need replacing. Both are production-tested conventions, not internal inventions.

Sources: Finsweet Client-First documentation (naming convention, folder system, global styles — verified 2026-05); Relume component library; Webflow University on breakpoints and CMS.