The following is a set of guidelines for building websites out of Breakdance. These guidelines have been developed in order to:
Introduce you to my preferred way of working
Explain development foundation
Maintain a consistent foundation from project to project
You'll find a combination of text instructions and videos below to help get you started. I suggest working through from top to bottom.
With each new project, be sure to check the Last updated date against each sub section and read through any that have changed since your last project with me.
Breakdance supports the addition of global CSS files. You can access these by clicking the three dot icon in top right corner of the editor then clicking Global Settings > Code.
This development foundation already has several stylesheets set up:
The first stylesheet contains some custom CSS variables, Breakdance global variable overrides, and any foundational CSS. This stylesheet is to be treated as a foundational stylesheet.
The second stylesheet is dedicated to Gravity Forms styles. It contains a foundation of GF CSS variables that allow us to easily set a custom style foundation for all Gravity Forms used on site. Only write CSS rules where a CSS variable cannot be configured to achieve the same result.
The third stylesheet is dedicated to custom CSS for Breakdance's Design Presets. Design presets don't have a CSS field and custom CSS to target the design preset's CSS classname is to be added to this file.
If the current project has a need for global CSS, create an additional stylesheet and put all the CSS in that stylesheet. Please be sure to document the CSS accordingly and maintain consistent formatting throughout.
Breakdance supports the addition of global JavaScript. You can access these by clicking the three dot icon in top right corner of the editor then clicking Global Settings > Code.
If the current project has a need for global JavaScript, create a additional scripts as needed. Please be sure to document the JavaScript extensively and maintain consistent formatting throughout.
Note that it isn't necessary to worry about firing scripts on events such as jQuery's ready or the native DOMContentLoaded event as Breakdance already wraps custom JavaScript Code in the DOMContentLoaded event handler.
JavaScript code added in this way is appended to the DOM in inline <script> tags.
Custom PHP snippets can be added to the site using the WPCodeBox plugin. I generally move all code from the Snippets Manager plugin into a custom logic plugin for the particular project. But whilst developing, it's totally fine to add code snippets to the interface provided by this plugin in WP Admin > WPCodeBox 2.
I'll often implement custom shortcodes where needed as opposed to using code blocks in the page builder and this is a great place to register custom shortcodes.
If you are adding custom PHP snippets, be sure to document the code clearly and extensively so it is very easy to understand.
Most websites I build require a simple text-based template for things like terms and conditions, privacy policies, etc. To account for this, this development foundation already has a template that is registered via PHP and that can then be targeted using a Breakdance template.
Coming soon
When working on a project with me you'll notice quite a lot of plugins on the installation.
Please do not activate any plugins or install any new plugins unless specifically asked.
If there is a plugin that you feel will really enhance the site, I'm open to hearing about it, but don't install anything before we have a discussion and I approve the installation of an additional plugin.
When defining new typography presets, use the approach where the first part of the preset specifies the name of the preset and then, where necessary, a right angle bracket followed by a variance name. e.g; Body copy > medium
Style presets should follow a similar convention to typography presets. The first part of the style preset name should reference the element. And then if there is some variation to specify, use a right angle bracket followed by the variance name. e.g; Button > Blue
CSS classes (known as 'selectors' in Breakdance) should follow the following conventions:
If the class is a utility class designed for general purpose use, use lowercase and prefix the class with "wolfd". e.g; .wolfd-no-margin
CSS variables should all have the "--wolfd-" prefix. e.g; --wolfd-section-width
PHP functions should all have the "wolfd_" prefix. e.g; function wolfd_get_post_count(){}
When inside a function or class, prefixes aren't necessary due to the scope but anything within the global scope must be prefixed.
The Custom CSS setting in an element's advanced settings are is a powerful feature that allows us to facilitate many more design possibilities within Breakdance.
When first using this field, you'll notice a %%SELECT0R%% tag in there which may be confusing at first. This is a twig variable used to target the specific element by a unique class name and should always be used when writing CSS at the element level.
Never use the element's unique CSS class name directly as this will fall apart when the element is copied and pasted elsewhere – the new instance would have its own unique CSS class name and the CSS in the Custom CSS field would no longer apply to the new instance.
Note that it is definitely possible and totally fine to append subclasses to the Twig placeholder. e.g;
%%SELECT0R%% .bde-heading {}
When setting typography spacing, always use relative units. This ensures font changes carry the same relative spacing.
Line heights are to always use the custom unit and are to have no unit appended to the input value – just use numbers. e.g; 1.4.
Letter spacing is to always use em values. If the design has a pixel value and divide that by the pixel font size and you will have the em value needed. If the design has a percentage value, divide that by 100 to get the em value.
When I design, I strive to stick to a 4-pixel system for the most consistent UI possible. i.e; I'll use any value that is divisible by four: 4px, 8px, 12px, 16px, 20px, etc.
Note that I also use 1px and 2px values a lot so it isn't a strict system but sticking to the system as much as possible enhances the user experience by making designs more intuitive, visually appealing, and easier to maintain.
There will, however, be designs that do not stick to this system, and are designed with a little bit more of a looser approach. If it's not clear what the spacing is, or if the spacing seems wildly inconsistent across the design, feel free to use any value from the 4-pixel system to maintain a degree of consistency.
Breakdance offers five breakpoints out of the box. When a lot of styles are distributed across many breakpoints, it can be hard to work out what's affecting what. So we need to be strategic in how we utilise the breakpoints.
Most of the time I focus on the Desktop, Tablet Portrait and Phone Landscape and only use breakpoints outside of these where necessary.
Additionally, when working CSS at the element level, I find it much easier to rely on CSS variables to modify values over breakpoints as opposed to writing the same selectors and CSS code for each breakpoint.
In Breakdance, the Columns element is a nice, convenient way to lay things out in column formats, but we should use it sparingly and when it makes sense to do so as it's just as convenient and easy to load up a few divs, and use something like CSS Flex and the Breakdance Layout Engine to set those elements up in a layout specifically formatted to our needs.
My general rule of thumb for using Columns versus Divs and Flex is to decide whether or not an element of the layout should indeed have a percentage based width or if it should be a fixed width. If that element does need to be fixed while the remaining elements expand to fill their container, I'll usually avoid using Columns in that situation.
With that in mind, I have on occasion written CSS that fixes the width of a column so there are ways to use columns with custom CSS to achieve a similar result, but generally speaking the layout engine in Breakdance is really powerful and we should take advantage of it where possible.
The first thing to do is to configure any CSS variables we have defined in our foundational CSS.
Click on the three dot icon in the top right corner next to the save button and then click on Global Settings.
Open the Code panel and then the first CSS stylesheet in the list.
Set the --wolfd-container-width variable to match the standard section width. This variable is used in Globals > Containers > Sections > Container Width and sets the default section width across the site.
All colours used on the site need to be entered into the color palette. Using the color palette ensures we maintain a consistent central location for managing colors site-wide.
Click on the three dot icon in the top right corner next to the save button and then click on Global Settings.
Click on the Colors panel and click the icon next to the Palette label.
If there are already colours in the palette, it will be for the wireframe system. Leave these in place as these will be cleaned up at the end of the build.
Add every colour we need for the current build into the palette. If we have many shades of a color, name each variations using a graduating number in increments of 100. e.g; Blue 100, Blue 200, Blue 300, etc.
Close the palette popup and set the Brand, Text, Headings, Links, and Background settings using the palette.
Click the Save button in the top right corner of the window.
Breakdance has global settings for two core button styles – primary, and secondary. Often, we'll need more than two styles to choose from and as of Breakdance 2.0, we can use style presets to house our button styles.
To make set up a little easier, there is a section housing buttons on the UI Components page.
Go to the UI Components page and open the page in Breakdance.
Find the section on the page titled Buttons.
Click on the three dot icon in the top right corner next to the save button and then click on Global Settings.
Click on the Buttons panel and click the icon next to the Primary label.
Configure the button settings as needed. Be sure to include the Typography > Advanced settings where line height and letter spacing can be set.
Repeat the above two steps for the Secondary button style.
Click the Save button in the top right corner of the window.
It's not uncommon to need more than two button styles. When we need more styles, we need to set up the buttons in the UI Components page and save their style as a style preset.
Go to the UI Components page and open the page in Breakdance.
Find the section on the page titled Buttons.
Add a new button alongside the existing buttons.
Under the new button's Design tab (paint palette icon), open the Button panel and select the Custom style.
Style the button as needed using the settings popup next to Custom.
Now either right click on the button and click Create Design Preset OR at the top of the design tab, click the design preset dropdown and click Create preset from design.
Name the preset using the Button > {name} convention. e.g; Button > Tertiary or Button > Call Us.
Click the Save button in the top right corner of the window.
Breakdance is quite good at providing us with a nice foundation on which we can customize to suit various needs and use cases. My preference is to lean on Typography Presets to configure the foundational typography styles so that I can then reuse those typography presets wherever needed.
Go to the UI Components page and open the page in Breakdance.
Find the section on the page titled Typography Presets.
Click on the three dot icon in the top right corner next to the save button and then click on Global Settings and then Typography.
Select the Body Font.
If the base font size is different to 16px, set the Base Size. Otherwise, leave it blank.
Open the Presets popup and open the Body copy > base preset. Configure the settings in here to match the base font size across the website. Be sure to set line height and letter spacing when specified. If not specified, choose sensible values.
If the design has small and large body font values, adjust these presets to match. If the design doesn't have these, remove the presets and delete the reference elements in the UI Components page.
You may also add more body copy presets here, if needed.
Click the Save button in the top right corner of the window.
Heading styles also utilise presets. A common use case these solve is the need to use specific heading tags (H1, H2, H3…) for SEO reasons but have those headings styled differently to the default styles for that heading level. This is where using typography presets as the foundation offers us a lot of flexibility.
In the global typography settings:
Select the Heading Font.
Open Advanced, then Headings, then All Headings. Do not set the Color, Font Family, of Font Size here as these are already set at the global level. If there is a common weight, line height, letter spacing, etc, that applies to all or multiple headings, you may set them here as the more specific heading element settings should override as needed. Just be sure to use relative values: e.g; custom and no unit for line height, em for letter spacing.
Close all popup windows and click on Presets. You will see typography presets for Heading 1 through to Heading 6 and can configure these as needed. Note that these are already set up with font sizes that scale using the Major third type scale which changes down to Major second on the mobile landscape breakpoint and below. If that doesn't apply to the current design, set these settings to suit the design.
Click the Save button in the top right corner of the window.
Design Presets are a convenient Breakdance feature but lack a custom CSS field. If we need CSS to style a preset, there is a global stylesheet set up for exactly that. The format we should use for selectors is:
.{element_type}.{preset_class_name} .{sub_selector}
Additionally, we should add a comment that mentions the name of the preset for easy referencing, prefixed with Preset:
For example, some CSS rules for a div element with a design preset containing a text element would look something like the following:
/* Preset: Div - Box with text */.bde-div .bde-preset-6a75b155-35ac-47be-afd5-d747ba25d604{ /* style rules here */ }.bde-div .bde-preset-6a75b155-35ac-47be-afd5-d747ba25d604 .bde-text{ /* style rules here */ }
Coming soon
