General

How to use this document

This is the branding-testing block, inside the vanilla system.
It is located in blocks/branding-testing

This block is hardcoded, and intended to be copied over to every new project.

This block allows you to see all global styles (buttons, forms, accordions, headings, etc.) defined in one place.
You may need to edit some of the html in this block (like color swatches, or add text classes) to fully test the design system.

The ACF group fields need to be exported from System – Branding Testing.
The Elements – Buttons ACF field group should also be cloned for this block to be completely functional.

Colors

Color CSS Convention

Colors are defined in css/colors.css
Colors differ project to project, but color classes should be declared similarly throughout projects.
All color variables should be defined with a variable inside of :root

Define a class outside of root with the same name as the color variable, for the global color class.
Define a class outside of root with _background following the variable name, for the global background-color class.
This allows easy color and background-color assignments throughout if needed, in both CSS and HTML.

:root {
    --brand-blue: #0044FF;
}
.brand-blue {
    color: var(--brand-blue);
}
.brand-blue_background {
    background-color: var(--brand-blue);
}

Using global background-color classes

Backgrounds for blocks are best declared on the same div: .container-fluid

<div id="<?php echo $block['id']?>" class="block-name-1 block">
    <div class="container-fluid brand-blue_background">
        <div class="container container-padding">
            [add further block html here]
        </div>
    </div>
</div>

Color Variable Swatches

Global color declarations are to be made in css/colors.css.
In new projects, declare all your background colors here and test that they work.
This way you have a swatch board of all the global colors used in the project.
These are the example color variables used in this project:

Standard Global Colors

Refined Palette

Icon Palette

Functional Colors

Buttons

Slick Slider Buttons

These are the slick slider buttons. Slick styles are located in css/slider/nw-slick.css
The slick arrow SVG file are located in css/slider/assets.
One SVG will work for both the prev and next button. The button.slick-prev is flipped with CSS, using this code:
transform: translateY(-50%) scaleX(-1);

Form Styles

Sitewide Form Fields

The text based input field styles here will automatically overwrite the text and select fields across the site.
The radio buttons and checkboxes however are only targeting the .wpcf7 class child markup.

CF7 Specific Style Overrides

Radio buttons & Checkboxes work off a two state SVG: selected or deselected.
SVG files for these are saved in css/forms/assets/checkbox and css/forms/assets/radio.
The acceptance fields by default have the checkbox selected and deselected SVG.

You have to copy the acceptance, radio and checkbox fields as they are in this theme for it to work properly with the CSS provided.

Key CF7 Field Markup/Shortcode

These are the key ways to build these inputs. Most inputs will have a label wrapped around them for accessibility reasons.
Some inputs require a particular method of writing code to achieve the effect desired with pre-written theme CSS.

Text input

<label>Text input field
[text* text-example placeholder "Placeholder text 1"]</label>

Select input

<label>Select input field
[select select-example "Option 1" "Option 2" "Option 3"]</label>

Email input

<label>Email input field
[email* email-example placeholder "email@address.com"]</label>

Telephone input

<label>Tel input field
[tel* tel-example placeholder "+44 7777 777 777"]</label>

Textarea input

<label>Textarea input field
[textarea textarea-example]</label>

Radio input

[radio radio-example use_label_element default:1 "Radio Example 1" "Radio Example 2" "Radio Example 3"]

Checkbox input

[checkbox checkbox-example use_label_element "Checkbox Example 1" "Checkbox Example 2" "Checkbox Example 3"]

Acceptance input

[acceptance acceptance-example use_label_element] By submitting this form, I agree that the information entered will be used in the context of my request for information in accordance with the privacy policy, personal data and data protection.[/acceptance]

Accordion

Using the accordion function

Accordion styles are defined in css/accordion.css
The accordion function is defined in the theme folder location lib/elements.php
The fields need to be cloned from Elements – Accordion in ACF.
The field prefix needs to be added to the cloned field in the block and inside the brackets in the get_accordion(); function.

There should only be one global style of accordion in the project.
If design have designed two, then ping it back to them, so it can be changed.

<?php get_accordion('branding_testing_accordion');?>

Gutenburg Blocks

Typical Block HTML

This is the typical HTML for a block when starting. Some blocks may differ slightly.

<div id="<?php echo $block['id']?>" class="block-1 block">
    <div class="container-fluid">
        <div class="container container-padding">
            <div class="row">
                <div class="col-12 col-lg-10 offset-lg-1">
                </div>
            </div>
        </div>
    </div>
</div>

Block PHP Declaration

This is the way a Gutenburg block is declared in lib/blocks.php.
After a block is declared, it can then be assigned specific ACF fields.

Declare the block

Declare the block in the list in lib/blocks.php
Place blocks of the same category close to each other in this file.

if( function_exists('acf_register_block_type') ) {
        // Block Category
        acf_register_block_type(
            array(
                'name' => 'block-1',
                'title' => __('block-1'),
                'description' => __('Generic block example. Give a more detailed description here.'),
                'render_callback' => 'my_acf_block_render_callback',
                'category' => 'block-category',
                'align' => 'wide',
                'mode' => 'preview',
                'icon' => $blocksIcon,
                'keywords' => array('Search result of block string', 'Another string'),
                'render_template' => 'blocks/content/block-1/block-1.php',
            )
        );
}

Enqueue the block CSS

Enqueue the CSS in the enqueue_block_styles(); function in the file.
This allows the block CSS to be used on every page; rather than just the page the ACF Gutenburg block is added on.

function enqueue_block_styles() {
    $template_url = get_template_directory_uri();
    wp_enqueue_style( 'block-1-style', $template_url . '/blocks/block-1/block-1.css' );
}

Allow the block in WP

All default and ACF blocks are disallowed by default.
They need to be added to this array in lib/blocks.php using this syntax, to be allowed in WP blocks.

/*** Allowed ACF Blocks Array ***/
$acf_blocks = array(
    // Block Category
    'acf/block-1',
)

Grid System

Container Conventions

Between projects we have three types of containers: .container, .container-fluid and .container-padding.
Container values are defined in css/main.css.

.container-fluid

Container fluid is a parent class assigned to a div inside all blocks.
It is usually either set to a max-width of 1920px or 100% for each project by default.
It can be changed to anything as long as the value is bigger than .container.
This ensures all of the web elements are constrained to a specified max-width and easily changed.

.container

Container is usually set to 1800px max-width.
Inside this container, usually blocks adhere to a col setting/offset of col-12 col-lg-10 offset-lg-1.
This ensures blocks do not touch the sides of the viewport on larger screens.

.container-padding

Container padding kicks in on at @media(max-width: 991.98px).
This ensures the gutter size for text for blocks underneath large viewports/on mobile.

<div class="container-fluid">
    <div class="container container-padding">
        <div class="row">
            <div class="col-12 col-lg-10 offset-lg-1">
            </div>
        </div>
    </div>
</div>

Responsive Breakpoints

Bootstrap breakpoints are used for responsive and deviation from these is to be avoided much as possible.

/* XX-Large devices (larger desktops) */

@media(max-width: 1399.98px) {
    /* xl breakpoint */
    /* X-Large devices (large desktops, less than 1400px) */
}

@media(max-width: 1199.98px) {
    /* lg breakpoint */
    /* Large devices (desktops, less than 1200px) */
}

@media(max-width: 991.98px) {
    /* md breakpoint */
    /* Medium devices (tablets, less than 992px) */
}

@media(max-width: 767.98px) {
    /* sm breakpoint */
    /* Small devices (landscape phones, less than 768px) */
}

@media(max-width: 575.98px) {
    /* xs breakpoint */
    /* X-Small devices (portrait phones, less than 576px) */
}

/* XS-Small devices (mobile phones) */

@media(min-width: 576px) {
    /* sm breakpoint */
    /* Small devices (landscape phones, less than 768px) */
}

@media(min-width: 768px) {
    /* md breakpoint */
    /* Medium devices (tablets, less than 992px) */
}

@media(min-width: 992px) {
    /* lg breakpoint */
    /* Large devices (desktops, less than 1200px) */
}

@media(min-width: 1200px) {
    /* xl breakpoint */
    /* X-Large devices (large desktops, less than 1400px) */
}

@media(min-width: 1400px) {
    /* xxl breakpoint */
    /* XX-Large devices (larger desktops) */
}