Builder Best Practices
In traditional web development, you can do just about anything in a number of different ways, but usually, one way offers more benefits than the others.
With the Builder Visual Editor, you are working with the underlying front-end code to access all of the robust features of modern development. Because of this, just as with code, you can do things in many ways with Builder.
This document covers best practices in the areas of:
Accessibility is an integral best practice for every stage of designing, developing, publishing, and iterating on all content.
Builder gives you the tools to create and iterate. However, as each use case is different, and because you can build an infinite array of digital experiences, just as if you were entirely coding your project, you must familiarize yourself with creating and maintaining accessible content.
Make sure that as you develop your projects in Builder that your content is accessible as defined by the World Wide Web Consortium(W3C), an international organization that develops and maintains web standards.
This document contains some instructions on where to edit your content along with links to accessibility resources in addition to W3C, such as WebAIM, a recognized leader in the field of web accessibility. For introductory guidance, refer to Web Accessibility for Designers.
Important: learn about responsive design
Many best practices assume a responsive foundation. Responsive design is a best practice in and of itself, whether you're coding or using a visual tool such as Builder.
This section shares some pointers, but to get a solid foundation in how to build successfully, whether you're coding or using a visual tool like Builder, read through the Builder Responsive Design documentation.
The Responsive Design docs explain the vital concepts of how browsers calculate what they display, width, margin and padding, alignment, columns, and fixing layouts, all with responsiveness in mind. And these docs are written from a no-code perspective, so anyone can learn how to build great responsive designs.
Keep pages short
In general, keep pages brief and to the point. Too much content can slow down your page and lead to lower conversion rates. Instead, create more, shorter pages with focused content and link to other pages of similar scope.
Make blocks full width with Full Page Width
When making a block as wide as the viewport, use the Full Page Width setting in the Style Tab. Though you can use a function manually in the CSS, the Full Page Width setting is quicker, intuitive, and prevents typos.
The following image shows where to find the Full Page Width setting in the Layout section of the Style Tab.
Keep Section blocks top-level
Nesting, or putting one thing inside of another, is generally a useful practice in web development; but Section blocks are best for containing other elements, rather than being themselves contained.
While you can safely nest items inside of Section blocks, don't nest Section blocks inside of other blocks.
A Section block's default styles are specifically for making the Section expand the entire viewport, so to use Section blocks with reliable, predictable results, keep them top-level, which means they can contain other blocks but should not be nested within other blocks.
The following image shows a Section block at the top-level in the Layers tab.
Nesting is useful for organizing, but avoid nesting too deeply as controlling the hierarchy depth helps keep the structure clear, which is helpful later for others who might work on what you've built.
Use the Style tab's graphical settings to style blocks. By relying on Builder's default styles and the Style tab's graphical settings, your design is more flexible and easier to maintain. Most of Builder's blocks are responsive out-of-the-box, which frees you to focus on the look and feel.
By using the graphical settings in the Style tab, and leaving the manual CSS styles to developers and designers versed in the nuances of CSS for responsiveness, your blocks and layouts become easier to iterate on and maintain.
Give targets recommended padding
When adding padding to a button, form element, or other target element, make sure it's big enough to accommodate a range of pointer inputs, such as a mouse, pen, or touch.
Though the recommended minimum of 24 pixels by 24 pixels is W3 Level AA accessible, the web development industry conventional standard of the enhanced Level AAA is 44 pixels by 44 pixels or the equivalent, which is informed by the W3 Web Content Accessibility Guidelines.
For instructions on how to use margins and padding in Builder, check out Margins and Padding.
Hiding a block
To hide a block, you can toggle the visibility on desktop, tablet, or mobile from the Visibility section of the Style tab. This toggle is preferable to changing the opacity for performance, especially in the case of sizable content.
Showing a block under certain conditions
When you want to show a block under specific conditions, use the showIf setting in the Data tab, rather than setting the opacity to zero. With the opacity set to zero, the user still has to load the element you've hidden, which can negatively impact performance.
For instructions on using
showIf, refer to this blog post.
Use Text blocks correctly
Set Text Blocks according to their semantic meaning. That is, if it is an
h1, select Heading 1 from the Text dropdown in the Edit settings–if it's an
h2, select Heading 2, and so on. Semantic Text Blocks improve accessibility, make styling easier, and are consistent with Shopify themes.
For semantic heading markup, use only one
h1 on a page and follow a clear hierarchy by making the next level of headings
h2, and those headings nested within an
Consider typeface and font size
In addition to color and contrast, you can improve the readability of text by carefully choosing the typeface and font size. Color, contrast, font size, and typeface all play a joint role in readability.
- To edit text styles:
- Go to the Style tab.
- In the Typography section, specify settings as needed.
For detailed information on text accessibility, refer to:
Paste text without styles
When copying text from another app and pasting that text into Builder, you might inadvertently paste the styles along with the text. To paste without styles in Builder, use one of the keyboard shortcut:
- On a Mac,
- On a PC,
Colors and contrast
When you're choosing colors for backgrounds, text, diagrams, or images, make sure the color contrast is accessible. To check if the colors you're using are accessible, use the WebAIM Contrast Checker. Enter your colors in the Contrast Checker to test if they pass accessibility standards.
To find the rgb or hex code for a color that's set in the Builder Visual Editor:
- Select the element where the color is set. For example, if the color is on the text, select that Text block.
- Go to the Style tab and go to the appropriate section. For example, if adjusting text color, expand the Typography section and click on the color swatch to display the color picker, which contains the hex and rgb codes.
- Copy the code you need and paste it into the appropriate WebAIM Contrast Checker field.
If the colors don't pass the WebAIM Contrast Checker, make adjustments in the checker to find colors that do pass. Paste the color codes that do pass into the Builder color picker.
To change colors in the Visual Editor:
- Select the block you want to change.
- Go the Style tab.
- For background colors, use the Background settings. For text, use the Typography settings.
These instructions are for colors set manually within the Visual Editor Style tab. As an alternative to setting colors manually, your developer can specify colors in a data model and you can bind to the colors. In this way, when the color changes in the model, all bindings automatically update the content to which they are bound.
For details on using data models for creating a Site Theme for managing colors, see Create a Site Theme.
Tip: These instructions for changing colors assume that you are using the Builder Visual Editor to set your colors and that you have access to change styles. However, many teams rely on Designers and Developers to specify colors in the CSS that blocks in Builder inherit.
If you find that changing the settings in the Style tab doesn't affect the change you want, you may want to reach out to your team's CSS point person.
Always use an Image block to add an image, rather than setting the image as a background on a block. Builder's Image block optimizes the image; however, the background image setting does not. Additionally, the Text block's alt text makes the block more accessible to screen readers than background images.
Always add alt text to images for accessibility. Make sure to use punctuation on alt text so that the screen reader pauses appropriately when reading the copy. You can find the Alt Text field by clicking the Edit button on the Image block.
Importantly, get familiar with the importance of alt text for accessibility by reading WebAim's Alternative Text.
For more information on the Image block in Builder, refer to Working with Images.
Provide information in a variety of ways
Use a combination of methods to convey information. Text, along with images, diagrams, videos, or other elements can help support differentiated access to information.
For more best practices check out the following:
Looking to hire a 3rd party to help with your project?
Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.