On this page you'll find examples on how to write HTML according to Dude Coding Standards.

Development at Dude

You are browsing the technical Coding Standards handbook of Dude, the Finnish digital agency. This handbook is supposed to be helpful for both internal and external members of Dude. It consists of best practices in programming at Dude.

Base for development

We are committed to keep this handbook under continuous development. If we notice issues in our tech, workflow, DevOps or anything related, we will improve on those areas. If you have any suggestions to this handbook, please send them to roni@dude.fi. Thanks!

What is Dude?

Our area of operation is currently Finland, but as we are a part for active WordPress community, actively publishing our tools and ways with open source licenses and using English as a development language, hence this documentation landing page is in English as well.

Related documentation

Wrong

Why it is wrong

In here we have a fully functional search form for visual people. However, labels contain text and inputs that are not accessible programmatically. Also in this example icon has been created by adding SVG inside label and hidden submit via styles. This means the user with keyboard or assistive devices can't use the form. Also for attribute is completely missing. Role is defined incorrectly for the form itself, that's wrong because form has role="form" explicitly built-in already.

<form role="search" method="get" class="search-form" action="/?">
  <label class="search-bar">
    <span class="screen-reader-text"><?php ask_e( 'Search: Search' ); ?></span>
    <input type="search" class="search-field" placeholder="<?php ask_e( 'Search: Search' ); ?>" value="" name="s">
  </label>
  <label class="icon">
    <input type="submit" class="search-submit">
    <?php include get_theme_file_path( '/svg/search.svg' ); ?>
  </label>
</form>

Right

Why it is right

<form method="get" class="search-form" action="/?">
  <div role="search">

    <label class="search-bar screen-reader-text" for="search-field">
       <?php ask_e( 'Search: Search' ); ?>
    </label>

    <input id="search-field" type="search" class="search-field" placeholder="<?php ask_e( 'Search: Search' ); ?>" value="" name="s">

    <button class="search-submit">
      <?php include get_theme_file_path( '/svg/search.svg' ); ?>
    </button>
  </div>
</form>

Under this doc you'll find out how you should do the markup of HTML elements.

Wrong

Why it is wrong

Hard to read.

<ul><li>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</li></ul>

Right

Why it is right

Easy to read.

<ul>
  <li>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</li>
</ul>

Wrong

Why it is wrong

In this example we have an empty hyperlink element that is still readable with screen reader devices. It tells the blind nothing so it's a huge accessibility issue. And that's not all, the element is also not browsable via keyboard because its styles fill up the whole column.

<div class="col">
  <a href="<?php echo esc_url( get_the_permalink() ); ?>" class="global-link"></a>
  <h2>Title</h2>
  <p>Descriptive text.</p>
</div>

Right

Why it is right

This example ignores the global link from screen readers and keyboards so that it serves only for seeing users. For assistive devices we use a normal link in title

<div class="col">
  <a href="<?php echo esc_url( get_the_permalink() ); ?>" class="global-link" aria-hidden="true" tabindex="-1"></a>
  <h2>
    <a href="<?php echo esc_url( get_the_permalink() ); ?>">
      Title
    </a>
  </h2>
  <p>Descriptive text.</p>
</div>

Resources

Section blocks

This is an example on what structure should be used in Gutenberg Blocks.

<section class="block block-example">
  <div class="container">
     <!-- Content -->
  </div>
</section>

PHP back-end development

Wrong

Why it is wrong

Assistive tools and keyboards see this as: paragraph, title. They are not linked to each other. For seeing users this is no problem as we have styled the small paragraph but for others it causes confusion.

Right

Why it is right

Disabling rules

If for some reason you need to use something that has been disallowed in phpcs.xml you should have good arguments in favor to it. You should comment the change accordingly:

<?php
// This rule is disabled in this file because...
// phpcs:disable WordPress.Security.ValidatedSanitizedInput.MissingUnslash

PHP Code Beautifier and Fixer (phpcbf)

With phpcbf it's quick to fix the most common errors that are not right accoring to your project phpcs.xml.

phpcbf --standard=phpcs.xml page.php

General linting and coding rules

You should always comment your code as thorough as possible. For indentation we use to char space. Always use the latest .editorconfig:

Blocks

Our custom blocks are named:

.block

Items inside block:

.block-header

.block-content

.block-footer

Items

These can be columns, upsells, grids, masonries, social media walls, logowalls, etc.

Parent

.items {
}

Children

.item.item-something {
}

Wrappers

Site-header and site-footer follow the WordPress guidelines:

.site-header {
}

.site-footer {
}

Content width container is always:

.container {
}

Something "smaller" like text:

.content {
}

Other general wrappers:

.wrapper-something {
}

Headings

We use heading instead of title.

.heading-something {
}

Icons

.wrapper-icons {
}

Buttons and links

Defined in _button.scss component.

.wrapper-button,
.wrapper-link {
}

The Guidelines are based on stylelint standards we have defined. Our stylelint config extends stylelint-config-standard and stylelint-config-recommended-scss. View the full .stylelintrc here:

Variable naming conventions

Defined format:

Examples for the root variable partials

Examples of how variables in block/component and other files could be named

We don't need separate breakpoint-specific variables.

We can just redefine the values of each original custom property within the scope of each media/container query. Which would work well if the nav mobile and desktop partials are ever consolidated in the future.

First we define the main fonts and then the context where we are using the font families.

:root {
  // Brand fonts
  --typography-family-whatever: Whatever;
  
  // Contexts
  --typography-paragraph: var(--typography-family-whatever);
  --typography-heading: var(--typography-family-whatever);
  --typography-upper-headings: var(--typography-family-whatever2);
}

Always check out your .stylelintrc for the latest rules. Aim for readable CSS. Use the "inception rule", do not go too deep.

Wrong

Why it is wrong

Too much speficity. Hard to maintain.

.block-example {
  > div.block-related-element {
    .element-that-should-be-global {
      a.something-specific {
        background: var(--color-background-block-example);
        color: var(--color-brand);
        font-size: var(--font-size-large);
      }
    }
  }
}

Right

Why it is right

We are just styling the link here so no need for extra nesting and specificity. Just cut to the chase and define with class.

.block-example .something-specific {
  background: var(--color-background-block-example);
  color: var(--color-brand);
  font-size: var(--font-size-large);
}

If it's going to be a global style, you can even simplify it and add it outside the scope. Remember to choose classes wisely.

.something-specific {

}

Change SVG colors the easy way with currentColor

If you need to change the color of the SVG with CSS, plug the currentColor value into the stroke and/or fill attributes. With currentColor, the color applied to the SVG will be the same color that’s already declared in the SVG’s parent element. You can also change the color to something else by adding a color declaration directly to an SVG ruleset.

svg.icon {
  color: var(--color-whisper);
}

svg {
  color: var(--color-east-side);
}

a svg {
  color: var(--color-purple-mountains-majesty);
}

Gutenberg block SVGs (i.e., the icons in the WordPress dashboard)

By default, the Gutenberg block icons in the WP dashboard will contain a black fill. Follow these steps to nuke that annoying fill:

1. Add a class name directly to the SVG. Ex: class="gutenberg-icon"

2. In the _colors.scss file, apply a color value (most likely, white) to the SVG, like so:

.gutenberg-icon {
  color: var(--color-white);
}

Styling commonly used SVGs

The plus-sign inside of the circle used in sub-menu toggles. Specifically, the SVG containing the line path that disappears on toggle/click.

Here’s the SVG’s code:

<svg class="dropdown-toggle-icon" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="11"/><path class="hide" d="M12 6v13"/><path d="M6 12h13"/></svg>

Add your new SVG file to the nav-walker.php file:

ob_start();

  require get_theme_file_path( 'svg/dropdown-plus.svg' );

  $icon = ob_get_clean();
  $output .= '<button class="dropdown-toggle" aria-expanded="false" aria-label="' . get_default_localization( 'Open child menu' ) . '">';
  $output .= $icon . '</button>';   

Now let’s hide that path. Add these rulesets and declarations to your theme’s nav files:

In _nav-desktop.scss

  .hover-intent > .dropdown-toggle svg {
    .hide {
      opacity: 0;
    }
  }

In _nav-mobile.scss

  .dropdown-toggle.toggled-on {
    .hide {
      opacity: 0;
    }
  }

When working with decorative SVG icons, add the aria-hidden="true" attribute to your SVG file.

Disabling rules

If for some reason you need to use something in different manner than declared in .stylelintrc you should have good arguments in favor to it. You should comment the change accordingly:

// Force color for color themes not to change this to unreadable colors
// stylelint-disable-next-line declaration-no-important

Important steps for all Dev Dudes to follow when adding SVGs to a project:

1. Manually remove clipPaths from the file. This includes <g>, <clipPath>, and <def> tags, plus any additional child elements wrapped in <def> tags. Here’s a visual example where the tags to remove are commented out:

<svg width="25" height="24" viewBox="0 0 25 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<!-- <g clip-path="url(#clip0_6597_3671)"> -->
<path d="M2.25 0.75H22.75C22.75 0.75 23.75 0.75 23.75 1.75V22.25C23.75 22.25 23.75 23.25 22.75 23.25H2.25C2.25 23.25 1.25 23.25 1.25 22.25V1.75C1.25 1.75 1.25 0.75 2.25 0.75Z" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M4.5 6.5V5H10.5V6.5" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M7.5 10.75V5" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M13.75 5H20" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M13.75 9.5H20" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M4.5 14H20" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M4.5 18.5H20" stroke="#3A3A3A" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
<!-- </g> -->
<!-- <defs> -->
<!-- <clipPath id="clip0_6597_3671"> -->
<!-- <rect width="24" height="24" fill="white" transform="translate(0.5)"/> -->
<!-- </clipPath> -->
<!-- </defs> -->
</svg>

1. Copy the viewBox attribute and its values.

3. Paste the viewBox attribute back into the file after the height attribute.

   • If the SVG is missing the viewbox attribute and its values, the SVG will be broken and the front-end Dude on the project will wonder why their pretty SVG styles aren’t showing up in the browser.