Building a Design System

This content was generated with the assistance of AI and should be verified against the official Webflow documentation before being relied on in production.

This sub-section’s Webflow bibliography lists the reference material consulted while preparing these pages.

This page was written against the Webflow Designer as it was on 2026-10-28. Webflow is a hosted service without version numbers, so the guidance below is dated by what the Webflow Way and the Webflow University checklist said at that check date, and https://webflow.com/updates announces product changes. Everything in the page can be practised on the free Starter Site plan inside a Starter Workspace, with two exceptions: sharing a design system with other sites needs a Workspace plan that includes Libraries, and the bulk-update features for many sites are limited to the Enterprise tier. Plans are named by tier only, and the current availability is listed in Plans, Workspaces, Seats and Roles.

The previous pages of this section explain the parts one by one: class naming, variables and modes, components and shared libraries. This page puts them together. A design system is not a Webflow feature with a switch: it is an agreement about which decisions are made once (colours, type, spacing, the shape of a card) and where they are stored, so that everybody who builds a page reuses them instead of redoing them. Webflow supplies the storage for each kind of decision, and the rest is discipline.

The running example is the Fernbrook Gardens site, a fictitious botanical garden. Fernbrook has a Home page, a Visit page, an events Collection and a ticket shop, edited by one designer, one developer and three marketers who write the weekly events. The goal is that the marketers can publish a new events landing page on a Friday afternoon without asking the designer for anything.

What a design system is made of in Webflow

The Webflow Way describes a design system as a set of variables, components and shared libraries, with a style guide that documents them. Each layer answers a different question and has a different rate of change.

flowchart TB subgraph L5["5. Pages and content"] P1["Home, Visit, events landing pages"] P2["Collection template pages"] end subgraph L4["4. Components"] C1["Visit Card, Events List, Nav, Footer, Hero"] end subgraph L3["3. Classes"] K1["Base classes: section, container, card, button"] K2["Combo classes: is-featured, is-secondary"] K3["Utility classes: u-text-center, u-padding-top-large"] end subgraph L2["2. Variables"] V1["Colour, size, font family, number, percent, link"] V2["Modes: Day and Night, or breakpoints"] end subgraph L1["1. Foundation"] F1["Naming rules, goals, accessibility targets"] F2["Style guide page and documentation"] end L1 --> L2 L2 --> L3 L3 --> L4 L4 --> L5 L4 -. "published to other sites" .-> LIB["Shared Library"] L2 -. "published to other sites" .-> LIB F2 -. "documents" .-> L4

Lower layers change rarely and affect everything above them; upper layers change often and affect only themselves. The practical rule that follows is to decide in the lowest layer that can express the decision. A brand colour belongs in a variable, not in a class value; a repeated card belongs in a component, not in six copied divs; a one-off layout tweak belongs on the page.

The Webflow University design system checklist organises the work in the same order: set up the foundation (goals, organisation, naming rules, a style guide, accessibility), create reusable styles and components, use interactions consistently, share and scale across sites, and document and maintain.

Source: Webflow University: Design system checklist

Layer 1: foundation

Before anything is built, three short decisions are written down. They cost an hour and prevent most of the later clean-up.

  • Goals. Fernbrook’s are "marketers assemble pages from approved parts", "the whole site can be re-themed for the winter season from one place" and "every page meets WCAG 2.2 level AA".

  • Naming rules. One of the systems from Class Naming Systems is chosen and its prefixes, separators and three examples are recorded. Fernbrook uses the Webflow Way: plain base classes, is- combos, u- utilities and a visit-card_title style for component parts.

  • Where the system lives. For a single site, the system lives in that site. For several sites it lives in a separate site that publishes a Shared Library, because the Webflow Way recommends a dedicated site for the design system so that its owners decide when edits are published to the sites that consume it.

Source: The Webflow Way: Libraries

Layer 2: tokens as variables

A design token is a named design decision, such as "the brand leaf green" or "large spacing". In Webflow, tokens are variables: a named value that can be applied to a style property in the Style panel. The Webflow Way calls variables the most atomic unit of a design system, because changing a variable changes every style that references it.

Variables are created in the Variables panel and are held in collections. Webflow’s own recommendation is to create variables for values that repeat, and to group them with a group/variable naming syntax, which the Designer shows as a folder. Fernbrook uses three collections.

Collection Contents Examples

Brand

The raw palette, named by what the colour is.

brand/leaf, brand/cream, brand/bark, brand/blossom

Theme

Colours named by their role, defined as aliases of the brand colours, with a Day mode and a Night mode.

theme/surface, theme/text, theme/accent, theme/border

Scale

Sizes for type and space, and the font families.

space/small, space/medium, space/large, type/body, type/heading, font/serif

Two levels are the important idea. A primitive variable holds a raw value (brand/leaf is a hex colour). A semantic variable holds a role and points at a primitive (theme/accent is an alias of brand/leaf). Components and classes should only reference semantic variables, so that a mode can swap the whole palette without touching a single class. The details of aliases, modes, the base mode and function variables are in Variables and Modes.

The CSS the variables produce

Each variable is published as a CSS custom property, with the group and the name joined by a double hyphen, and a class that uses it refers to it with var(). The Fernbrook cards from the previous pages therefore publish like this:

:root {
  --brand--leaf: #2f6b3f;
  --brand--cream: #f6f1e5;
  --theme--surface: var(--brand--cream);
  --theme--accent: var(--brand--leaf);
  --space--medium: 24px;
}

.visit-card {
  background-color: var(--theme--surface);
  border: 2px solid var(--theme--accent);
  padding: var(--space--medium);
}

Because the tokens are plain custom properties, a developer can use the same names in an embed or in a script, and a designer working in the Style panel sees the same name. A Night mode applied to an element changes the values of the semantic variables inside that element, which is how a dark footer can sit in a light page.

Source: Webflow Help Center: Variables

Creating tokens by script

When a design system has to be created on many sites, or kept in step with a design file, variables can also be created from the Designer API. The following sketch, run from a Designer Extension, creates the Fernbrook brand collection. The values are the same placeholders as above.

import type {} from "@webflow/designer-extension-typings";

const collection = await webflow.createVariableCollection("Brand");
await collection.createColorVariable("leaf", "#2f6b3f");
await collection.createColorVariable("cream", "#f6f1e5");

Source: Webflow Designer API: Create color variable

Layer 3: classes and utilities

Variables store values, and classes decide where those values are used. The classes of a design system are of three kinds, as described in Class Naming Systems: base classes for the structural pieces, combo classes for variations, and utility classes for single-purpose styles.

For Fernbrook the base layer is deliberately small:

  • section, with the vertical padding taken from space/large;

  • container, with a maximum width and the horizontal padding;

  • card, button and heading, each referencing semantic variables only;

  • a handful of utilities: u-text-center, u-padding-top-large, u-visually-hidden.

Three habits keep this layer healthy. First, set the global styles that apply to bare tags (the body, the headings and the links) on the tag selectors in the Style panel, so that a heading looks right even before it has a class. Second, resist a utility per value: since variables arrived, a size or colour does not need a utility, and a utility is justified only when it applies a combination or a property that a variable cannot express. Third, keep responsive behaviour in the base classes and in variable modes for breakpoints, not in one-off overrides on each page; the cascade is explained in Responsive Design and Breakpoints.

Source: The Webflow Way: Styles

Layer 4: the component library

A component packages an element tree, its classes, its properties and, if needed, its slots and variants. In a design system the component library is the part that marketers see and use, so it deserves the most care. The full mechanics are in Components, Props, Slots and Variants; the points that matter for a system are these.

  • Choose what becomes a component. Navigation, footer, hero, card, call to action, events list and the newsletter form recur on most pages, and each is a component. A one-off layout that appears once is not.

  • Expose only what an editor should change. A property per editable thing (title, image, link, badge text) and nothing else. Every extra property is a decision the marketer has to make, and an unexposed style cannot be broken.

  • Use slots for flexible regions. A section component can offer a slot for its content, so a marketer can place a card, a rich text block or an image inside a standard section frame without being able to alter the frame.

  • Use variants for approved alternatives. The Visit Card has a Default and a Featured variant, chosen from a drop-down in the instance settings, so the choice of look is one click and is limited to what the designer approved.

  • Name for the person who searches. Component names are plain words (Visit Card, Events List), and related components are grouped, because the Components panel is searched by typing.

Fernbrook’s library after the first month looks like this:

Component Properties Slots Variants

Nav

Logo link, call-to-action text

None

Default, Transparent (for hero pages)

Hero

Heading, introduction, image, button text and link

None

Default, Short

Visit Card

Title, text, image, link

None

Default, Featured

Section

Heading

Content

Light, Dark

Events List

Heading, number of items

None (fed by the Events Collection)

Default, Compact

Footer

Opening hours text

None

Default

Components are also where the accessibility of the system is made repeatable. A component whose root is a nav with a label, whose image property has an alt text field and whose heading level is a property cannot be assembled without those pieces. Accessibility is covered in Accessibility.

Source: Webflow Help Center: Components overview

Layer 5: the style guide page

A style guide is a page, usually unlisted from navigation and search, that shows every token and every component in use. It has two audiences: designers, who see at a glance whether something is already defined before they invent it, and reviewers, who can check the whole system in one scroll. The University checklist suggests organising it by category: typography, colour, spacing and components.

Fernbrook’s style guide is a page called /style-guide with these sections:

  1. Colour. One swatch per semantic variable, shown in the Day mode and again inside a wrapper using the Night mode.

  2. Typography. Every heading level, the body text, the links and a long rich text paragraph, which shows the combined result of the tag selectors and the rich text rules.

  3. Spacing. A row of boxes using space/small, space/medium and space/large.

  4. Components. One instance of every component and every variant, placed in a section.

  5. Naming rules. The one-page summary of prefixes, separators and examples from the foundation layer.

  6. Accessibility notes. The contrast ratios table described below, and the rules about alt text and heading order.

Two details make the page reliable. It is built only from the real variables, classes and components, so it can never drift away from what the site uses; if a swatch is wrong, the system is wrong. And it is excluded from search engines and from the sitemap, using the page’s SEO settings, so it stays an internal tool. Those settings are explained in SEO and AEO.

Sites generated by Webflow AI arrive with a style guide page of their own, built on the Flowkit conventions described in the class naming page. It is a good starting point to adapt, and the Webflow Marketplace also offers cloneable style guides and frameworks.

Source: Webflow University: Design system checklist

Accessibility checks inside the system

The cheapest place to meet accessibility requirements is in the tokens, because a contrast failure fixed in a variable is fixed everywhere. The Web Content Accessibility Guidelines (WCAG) set minimum contrast ratios between text and its background: 4.5 to 1 for normal text and 3 to 1 for large text and for the boundaries of interface components, at level AA.

For Fernbrook the check is done once, for every pair of semantic variables that are used together, and the result is written in the style guide:

Text colour Background Approximate ratio Use

theme/text (dark green)

theme/surface (cream)

8.6 to 1

Passes for body text.

brand/leaf (mid green)

theme/surface (cream)

About 5.6 to 1

Passes for text and for borders.

A candidate light green

theme/surface (cream)

About 2.2 to 1

Fails: rejected for text, allowed only for decoration.

The ratios are computed with any contrast checker, such as the one built into browser developer tools, and they must be repeated for the Night mode, because swapping the base colours produces a different set of pairs. The checks belong to the system’s routine, not to each page: when a new brand colour is proposed, it is tried against the surfaces first.

Other checks are part of the components instead of the tokens: a visible focus style defined once on the interactive base classes, a minimum size for tap targets on buttons, the heading level exposed as a property so pages do not skip levels, and a required alt text field on every image property. The Designer’s Audit panel then reports the problems that remain on a page, and the system’s reviewers run it on the style guide after every change.

Source: Webflow Help Center: Intro to the Audit panel

Marketers building pages from components

The test of a design system is whether the people who are not designers can use it. Fernbrook sets the Workspace roles so the system and the content have different owners. The designer and the developer hold full access to the design; the marketers are given Content Editor access to the site, which lets them edit text, images and properties on the canvas but not styles, classes or variables. The roles are described in Plans, Workspaces, Seats and Roles and the editing experience in Content Editing on the Canvas.

A marketer building the "Winter lights" events landing page works like this:

  1. Opens the site in the Editor and chooses an existing page, or asks the designer for a page created from the standard landing page template, which already contains Nav, Hero, an empty Section and Footer.

  2. Edits the Hero properties: the heading, the introduction, the image with its alt text and the button.

  3. Fills the Section slot with a Visit Card for each evening, choosing the Featured variant for the opening night, and changes the card properties on the canvas.

  4. Adds the Events List component and picks the Compact variant, so that the list is fed by the Events Collection with no layout decision to make.

  5. Previews the page, and publishes it. If Fernbrook uses page approvals or scheduled publishing, the marketer submits it instead, as described in Page Branching, Releases and Approvals.

The marketer never types a class name, never chooses a colour and never alters a spacing value, and the result still follows the system, because each of those choices was made in a lower layer. If a marketer needs something that does not exist (a gallery of six images, for example) the request goes to the designer as a component request. That route is deliberate: a missing component is an input to the system, not a reason to bypass it.

Source: Webflow Help Center: Components overview

Sharing the system with other sites

When Fernbrook opens a second site for its plant shop, the design system moves into a dedicated site that publishes a Shared Library. A library can contain components, variables, fonts and assets. Consumer sites install the library and then accept updates, and the consuming sites cannot change the shared parts, which keeps the brand identical. The steps, the Workspace scope, the rule that an installed library cannot itself be shared again and the Enterprise features for bulk updates are in Shared Libraries.

Two practices make sharing safe:

  • Treat the library as a product. Changes are made in the library site, tested on the style guide, and only then published. The Webflow Way recommends the separate site precisely so that edits are made and previewed privately and published at a chosen moment.

  • Use modes for brands. When two sites share the structure but not the palette, a variable mode holds each brand’s theme values, so the components are shared and only the mode differs.

Source: Webflow Help Center: Using a design system in Webflow

Documentation and governance

A system that nobody can learn is not shared. The University checklist asks for three things in its last stage: document how the system works, define who can update it, and audit and update it regularly. Fernbrook turns these into a small routine.

Question Fernbrook’s answer

Where is the documentation?

The /style-guide page for the visual reference, and a one-page text in the Workspace’s shared notes for rules and naming. Nothing is documented only in a person’s head.

Who may change tokens, classes and components?

The designer and the developer. Marketers have Content Editor access, and a request for a change is a ticket.

How is a change made?

In the Designer on a branch of the page or, for a shared library, in the library site first. The change is checked against the style guide and the contrast table, then published.

How are changes announced?

A short note in the team channel, with the changed component or variable and the sites that need to accept the update.

When is the system audited?

Once a quarter: unused classes are removed with the Style selectors panel, unused variables and components are reviewed, duplicates are merged and the contrast table is re-run.

What happens to the old version of a design?

The activity log and the site backups keep a history, described in Collaboration, Comments and Activity Log and Backups and Recovery.

Governance also covers what the Designer cannot enforce. Class names, variable groups and component names are conventions, so a review step catches the exceptions. A good minimum is one question at the end of every design change: could a marketer have done this with the existing parts, and if not, should a new part be added to the system?

Source: Webflow University: Design system checklist

Common mistakes and pitfalls

  • Building components before tokens. A component full of hard-coded colours must be edited by hand when the palette changes. Create the variables first, then the classes, then the components.

  • Referencing primitive variables in components. A class that uses brand/leaf directly cannot follow a Night mode. Reference theme/accent.

  • Too many properties. A component with fifteen properties is a form, not a building block. Split it, or turn some choices into variants.

  • A style guide that is hand-copied. Screenshots or retyped values drift. Build the style guide from the real parts.

  • Unlimited variants. Variants multiply quickly; when a component needs more than a few, check whether it is really two components.

  • Skipping the dark mode contrast check. A palette that passes in the Day mode can fail once the aliases point at other colours.

  • Publishing library changes without a preview. Consumer sites receive updates only when they accept them, but the library’s owners should still verify the change on the style guide first.

  • Treating the system as finished. A system without an owner decays within months. Name an owner and keep the audit on the calendar.

Security and privacy notes

A style guide page and a library site are public if they are published, and unlisted is not the same as private. Keep draft brand colours, internal notes and unreleased campaign names out of a style guide that is published to a live domain, or protect the page with a password, as described in Password Protection and Site Search. Class names, variable names and component names that appear in the published HTML and CSS are readable by anyone, so they must not contain client names or internal ticket numbers.

Corrections to older tutorials

Older books and tutorials, including Webflow by Example (Packt, 2021), pre-date variables, components with properties, slots and variants, and Shared Libraries. They build a "style guide" by hand with copied classes and use Symbols as the only reusable unit, and they store colours as swatches rather than as variables with modes. In the current Designer, tokens are variables, reusable parts are components with a controlled editing surface, and sharing across sites is done with libraries. The advice to create a utility class for every value is also overtaken by variables, and the naming advice is updated in Class Naming Systems. The history of the changes is in Where Older Books and Tutorials Are Outdated.

References