This document describes requirements for tools, style structure, and how should be built and support the website design.
Tools:
...
- Figma
...
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
...
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.
...
- 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
- Preferred classes order in HTML: blocks, mixins, JS-hooks, states:
<div class="upload-files scrollable js-files is-hidden"> |
|---|
Single tag structure
styles
| folder width tag styles specific for that tag and wrapped in the tag selector |
| widgets | folder with tag widgets files what included to main.tag. All widgets have unique styles files in tag styles folder what included to tag |
| main.tag | root tag file |
...
- content
- z-index
- position
- top
- right
- bottom
- left
- overflow
- float
- display
- visibility
- opacity
- width
- height
- margin
- padding
- border
- outline
- box-sizing
- list-style
- background
- font
- line-height
- text
- letter-spacing
- white-space
- transition
- animation
- color
- cursor
- @include
...
- cursor
- @include
NoticeNever use `@extended` SCSS function, because it creates a lot of nested rules and makes CSS file fat. |
|---|
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/
Notice
...
...
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.