The Berrario UI Library is built to keep projects consistent, fast to assemble, and easy to scale. These guidelines explain how to use the system the right way—so components stay predictable, upgrades stay painless, and teams don’t drift into one-off builds.
Why We Built The Library
The Berrario UI Library was built to make creating consistent, scalable interfaces faster and more dependable. It brings reusable elements, components, responsive layouts, interactions, and Custom Behavior systems into one structured foundation, reducing repeated setup while keeping design and functionality aligned across the project.
The Library also creates a shared system that is easier for teams to learn and maintain. When new people join a project, they can quickly understand its structure, naming conventions, and behavior rules instead of learning a different setup for every page or component.
The Style Guide is also designed as a working environment where teams can build new elements and components as projects evolve. By following the established structure and documenting additions in one central place, teams can keep the system organized, maintain consistency, and preserve a clear record of how each part should be used.
This gives teams a reliable foundation they can adapt and expand without losing clarity as the project grows.
This UI Library is built for both beginners and professionals.
Whether you are learning Webflow, building faster for clients, or creating a more consistent design system, this library gives you a strong starting point without limiting how far you can take it.
Inside Pages (P), the UI Style Guide folder is organized into three sections:
Keep Style Guide components as clean base references. Do not add project-specific content or extra elements directly inside built components like poppers, popovers, modals, or similar systems in their Style Guide placements. Place the component on the page and customize it there, or create a custom container in the Style Guide if the adapted version will be reused across multiple pages. The Style Guide should remain the base source for choosing a solution, with edits limited to system-level settings such as color, spacing, typography, and sizing.
Consistency in naming is what makes the library usable at scale.
Base Class First, Addons Second
Always apply the base class first, then layer addons.
This keeps styling predictable and prevents “mystery UI” caused by stacking unrelated combo classes.
Avoid One-Off Combo Classes
If a UI decision is likely to show up more than once, it should be part of the system.
Use a one-off class only when:
If it affects component behavior (spacing, layout, interaction patterns), it belongs as an addon or a new documented element.
Build With Structure, Not Styling
The library is designed to be assembled like a kit:
When spacing feels off, the correct fix is usually:
Keep Class Names Stable
Avoid renaming base classes and addons. Many styles rely on intentional class combinations.
For example, flex-horizontal + flex-align-center-center works because the combo class flex-horizontal flex-align-center-center contains the alignment rules. If you rename either class, that combo link breaks and the alignment styles won’t apply.
If you need to rename a class, first check whether it’s used as a combo class with other classes, remove it as a combo class, then rename it.
Addons Should Stay Focused
An addon class should do one job.
Good addons:
Avoid addons that:
If an addon starts becoming a “bundle,” it should be split into clearer addons.
Library components should remain accessible by default.
If a component changes semantics, treat it as a deliberate variant and document it.
The library is designed to behave predictably across breakpoints.
If a component needs breakpoint-specific behavior, it should be defined as a documented pattern—not an ad hoc adjustment.
This component is already included in Page Templates, so any page created by duplicating a template will include it by default. Make sure to add it to all custom-built pages and CMS template pages going forward so the required global systems load correctly.
Components in the Library are organized as either Local or Global, depending on how their triggers and targets are connected.
Local Components are usually controlled through Webflow’s native Interactions. In most cases, the trigger and target sit inside the same parent structure, often as siblings or closely related elements. This keeps the behavior specific to that component, section, or layout.
Local systems may also use interaction addon classes connected to the main class, such as i-local, i-click, or i-hover. These addons help separate interaction behavior from the base element class while keeping the interaction tied to the local structure.
Global Components are built as reusable infrastructure for custom behavior systems. Their triggers and targets do not need to sit inside the same parent structure. Instead, they are connected through documented attributes, class hooks, addon classes, and required naming conventions, allowing them to control each other from different places on the page.
Use Local Components when the interaction belongs to one contained layout.
Use Global Components when the behavior needs to work across the page or across multiple reusable components. This is where Custom Behavior Systems are used.
Custom Behavior Systems act as a reusable infrastructure layer for more advanced UI behavior. They extend what can be built inside the Designer by connecting components through documented attributes, class hooks, addon classes, and consistent structure, while keeping the system easier to manage and update from one central place.
Custom behavior systems are saved as components, making them easy to place where needed while keeping everything centralized in the Style Guide for maintenance and updates.
Systems like Modal, Popover, Cookie Consent, and other global behaviors work because structure and naming stay consistent.
Guidelines for custom behavior elements:
If a layout needs a different structure, that should be handled by creating:
When updating custom code, test changes thoroughly before publishing. Global code updates can affect multiple pages and components at once.
Important
The Variables panel is the foundation of the Berrario UI Library. It centralizes the system’s design decisions (color, spacing, typography, borders, and layering) so components stay consistent, scalable, and easy to update without chasing values across dozens of classes.
The structure is intentionally grouped in a way that mirrors how UI is built in real projects: core foundations first, then semantic tokens, then component-specific tokens.
Colors are structured in layers so you can change the brand look once and have it update everywhere—without breaking component styling.
Why this structure: Theme stays flexible, while components stay stable because they rely on semantic roles instead of hard-coded colors.
Scale holds the system’s spacing and sizing logic. Instead of storing random pixel values per component, everything maps to consistent step-based tokens.
Why this structure: it prevents “design drift” and keeps spacing decisions system-driven, not page-by-page.
Border variables are organized into three groups: radius scale, component radius, and border size.
Why this structure: some components need specific corner behavior, while the system still needs a reusable scale for everything else.
Typography variables separate font identity, readability rules, and responsive scaling.
Why this structure: typography changes are high-impact—this setup lets you adjust readability and hierarchy globally without breaking components.
Z-index is grouped by purpose so layering stays predictable and avoids random z-index values.
Why this structure: overlays and floating UI systems only work reliably when the layering model is consistent across the entire build.
The Assets panel is organized to keep files easy to find, consistent to use, and safe to maintain over time. Instead of storing everything in a single bucket, assets are grouped by purpose so projects stay clean as the library grows.
Folder Structure
Guidelines
Animations in the UI Library are primarily built with Webflow Interactions. Any class that is an Interaction trigger will show the Interaction icon 🗲 next to its class name in the Designer.
Important Notes
Interactive components rely on predictable states that are mainly controlled by native Interactions (X) or custom code through adding and removing classes.
----------------------------
The goal is simple: state is readable in the Navigator, and behavior stays consistent everywhere.
If interactions are used, they should enhance transitions—not replace the logic of the system.
This library includes custom SVG icons added as SVG code. SVGs can be styled directly through their parent element, allowing properties such as color, size, opacity, and hover states to remain consistent with the design system.
Editing SVGs
To replace an SVG, open the element containing the SVG code and replace the complete <svg>...</svg> markup with the new SVG code.
When replacing an SVG:
Changing the Color
SVGs that use currentColor inherit the text color of their parent element. Change the parent element’s color to update the SVG without editing its code.
Changing the Size
Adjust the width and height of the SVG wrapper or SVG element. Keep the original aspect ratio to prevent distortion.
Important
Do not remove required classes, attributes, or wrappers connected to interactions or custom behavior. Replacing only the internal SVG code helps preserve the existing layout and functionality.
In Site Settings > Forms, you may see a form named Untitled Form. This is expected.
The UI Library includes form elements inside the Style Guide and certain components that are used for structure and interaction—not for collecting or submitting information. For example, components like Cookie Preferences may use checkboxes, switches, labels, and form wrappers so the interface behaves like a real form, but the data is handled by custom code instead of being submitted through Webflow Forms.
Because these elements still use Webflow’s native form structure, Webflow may register them under Forms as Untitled Form.
Do not delete or rename these form structures unless you fully understand where they are used. They may be required to keep form-based UI elements, switches, preferences, and component layouts working correctly.
If you build a real contact, signup, or lead form, give that form a clear custom name so it can be easily separated from system-based forms used only for UI behavior.
The Style Guide is the central workspace for reviewing, editing, expanding, and documenting the UI Library. It keeps the system’s elements, components, examples, instructions, and behavior references organized in one place so teams can maintain a consistent structure as the project grows.
Documentation Page
Use the existing Documentation Template as the starting point when adding a new element, component, or system to the Library. Duplicate the page and keep the established documentation structure wherever it applies.
The page includes reusable sections for headings, subheadings, component examples, class structures, notes, interaction references, Custom Behavior instructions, and user guides. Starting from this page helps new additions remain consistent with the rest of the Library.
After duplicating the page:
Style Guide Components
Reusable documentation components are available in the Components panel under the Style Guide category. Open the panel using Shift + A and place the required component into the Documentation Page.
These components help keep repeated documentation elements consistent, including notes, class displays, item wrappers, navigation elements, code references, and other Style Guide structures.
Edit these components carefully, as updates to a shared documentation component may affect multiple Style Guide pages.
Style Guide Class Names
Classes used only inside the Style Guide follow the base name Berrario Style Guide, with addon classes using the b- prefix.
This naming is intentional. It keeps documentation and Style Guide layout classes clearly separated from production classes, preventing overlap, conflicts, or accidental reuse inside live components.
Do not use Style Guide classes to build production layouts. When creating a new documentation structure, reuse the available Style Guide classes and components before creating additional ones.
Keeping the Style Guide Organized
Place new documentation in the category that best matches its purpose, and follow the existing page and section hierarchy. Reuse established naming, layouts, components, and documentation patterns wherever possible.
The Style Guide should remain a reliable record of how the system is structured and used. Any new element or component added to the Library should also be added to the Style Guide with enough information for someone unfamiliar with the work to understand, edit, and reuse it without guessing.
If you add something to the library, document it.
Every element should include:
The goal is: someone new to the system can use it without guessing.
A component is done when: