Website Develop Guide

This document describes requirements for tools, style structure, and how should be built and support the website design.

Tools:

• Design
  • Figma
• Code Tools:
  • SCSS
  • Webpack
  • HTML template preprocessor (like blade etc.) 
  • Yarn

Good WordPress boilerplate theme with correct structure https://roots.io/sage-9/

Design methodology: Aatomic Design Methodology

Design

Major points:

• research current website, define week places and goals
• build a prototype in figma or in another prototype builder
• build base styles and pages
  • A designer must provide and support style guide page where will be described common elements, scaffolding, base widgets, and feature pages should be based on this style guide, old pages must mutate views with a style guide.
  • After implementation design and style guide in figma, the developer should realize the style guide in code. It means The website must have the protected page where will be rendered all widgets, buttons, etc. with description, MAN. (Good example it is Bootstrap documentation).

Style folder structure based

themes/current_theme/                            # → Root of your Sage based theme
...
└── resources/                                   # → Theme assets and templates
    └── assets/                                  # → Front-end assets
        ├── config.json                          # → Settings for compiled assets
        ├── build/                               # → Webpack and ESLint config
        ├── fonts/                               # → Theme fonts
        ├── images/                              # → Theme images
        ├── scripts/                             # → Theme JS
        └── styles/                              # → Theme stylesheets
             ├── common(core)                    # → Fonts, global styles, variables, base scaffolding
             ├── mixins                          # → Custom mixins and functions
             ├── components                      # → Buttons, Link etc. base elements
             ├── widgets                         # → Base widgets like section, modal, forms, header, footer etc.
             ├── layouts                         # → Page layouts based on widgets with uniques styles for page
                 └──  layout_name                # → Folder with layout styles
                      ├── widgets(blocks)        # → Unique layout widgets or overwtires of common widgets
                      └── layout_name.scss       # → layout with imported layuot widgets
             ├── lib                             # → Imported styles from npm packages and their overrides 
             └── main.scss                       # → Main file where imported all files (mixins, node modules, lib, core, components, widgets, layouts)

CSS classes names

All classes must be named with a sense of content and completeness. For example: .product-card, .product-card-logic_elem, .btn.btn-small.btn-success, etc.

Almost the same style as in BEM. Blocks are .block, elements are .block__elem, but modifiers are .block-modifier_name instead of .block_property_value.

tag  ID in camel case #teamListForm

Cascade usage

Allowed for:

• To define a context. E. g. a block should look differently on light and dark backgrounds: it can be achieved by using a modifier or using a cascade (adding context class to body tag or to parent block).

• To use semantic classless tags in user-generated content (articles, comments, etc.).

• (Very rarely) when you are sure you will never put nested block with the same tag.

Mixins

Kind of OOCSS. It’s a normal block but intended to extend another (primary) block, to add some look or behavior.

States

It’s like modifier but you can use it with any block or element. Very useful in JavaScript.

JS-hooks

You shouldn’t use CSS classes used to style content to select elements in JavaScript. (Except states.)

Wrappers

Don’t imply any semantics, use it for appearance only.

Caveats

1. Preferred classes order in HTML: blocks, mixins, JS-hooks, states:

Single tag structure

Style properties order

1.  content
2.  z-index
3.  position
4.  top
5.  right
6.  bottom
7.  left
8.  overflow
9.  float
10.  display
11.  visibility
12. opacity
13.  width
14.  height
15.  margin
16.  padding
17.  border
18.  outline
19. box-sizing
20.  list-style
21.  background
22.  font
23.  line-height
24.  text
25.  letter-spacing
26.  white-space
27.  transition
28.  animation
29.  color
30.  cursor
31.  @include

Images

• Add method to theme common controller, which will be detecting client device and return optimal image size for fast page loading via wp_get_attachment_image( $attachment_id, $size, $icon, $attr );
• Integrate WEBP images

Icons

For add new icon to project use https://icomoon.io/app/

Javascript

Is a good example how to build js for the Wordpress: https://roots.io/sage/docs/theme-development-and-building/, this method a part of Sage boilerplate theme.
The Main idea is to build and fire javascript by native body classes which uniques for every page, page entity, etc.

ACF

Styleguide: https://www.advancedcustomfields.com/blog/best-practices-designing-custom-fields/