NOTE: Many ideas have evolved since I originally wrote this doc. Read my updated gist here.
Alwasy follow DRY (Don’t Repeat Yourself) fundamentals.
All features and layouts are referenced in index.php.
All php functions are referenced in functions.php.
Javascript is written in functions.js, and javascript plugins are located in the scripts\ folder.
Images are in the images\ folder.
Original style is referenced in the sass\ folder.
Theme SCSS is segmented into ‘elements’ (general HTML elements), ‘helper_classes' (global css classes), ‘template_parts’ (features, layouts, loop_content, footer elements, header elements, and sidebar elements), and ‘variables’ (global SASS variables). All sass templates are imported into style.scss, then compiled and minified into the style.css file in the theme's home directory.
Additional code that has unique purpose, like style-tinymce.css, can be added to the theme’s home directory.
Basic Theme Architecture:
theme_name/
├── header.php
├── index.php
├── functions.php
├── includes/
├── functions.js
├── scripts/
├── style.css
├── style.scss
├── sass/
│ ├── elements/
│ │ ├── _buttons.scss
│ │ ├── _forms.scss
│ │ ├── _images.scss
│ │ ├── _links.scss
│ │ ├── _tables.scss
│ │ └── _text.scss
│ ├── fonts/
│ ├── helper_classes/
│ │ ├── _backgrounds.scss
│ │ ├── _effects.scss
│ │ ├── _grid.scss
│ │ ├── _sizing_and_alignments.scss
│ │ └── _wordpress.scss
│ ├── template_parts/
│ │ ├── _features.scss
│ │ ├── _footer.scss
│ │ ├── _header.scss
│ │ ├── _layouts.scss
│ │ └── _loop_content.scss
│ └── variables/
│ ├── _colors.scss
│ ├── _effects.scss
│ ├── _element_sizing.scss
│ └── _typeography.scss
├── template_parts/
└── footer.php
Template parts help with organization and avoid code redundancy.
Each template part falls into one of six types:
- layout : A site layouts (ie-
layout-front_page). - feature: A content element that can be loaded without the loop.
- loop_content: Content that relies on the loop.
- header: Content that's only in the site's header.
- footer: Contant that's only in the site's footer.
The template part naming convention is: <type>-<name>.php.
For instance, a template part that we use to recent posts is named feature-recent_posts.php.
All template parts include a parent wrapper div with a class reference to the template part in this format class="<type>-<name>
Example:
<div class="feature-recent_posts">
...
</div>
Child elements should reference their parent's name before referencing their own name. All names should be unique and descriptive. The format is class="<parent/type>-<name>.
Example:
<div class="feature-recent_posts">
<div class="recent_posts-single_post">
...
</div>
</div>
Avoid referencing style helper classes in class name.
Do this:
<div class="feature-recent_posts">...</div>
Don't Do This:
<div class="feature-recent_posts color-red"></div>
Helper classes should be referenced in the scss code.
Example:
.feature-recent_posts{
@extend .color-red;
}
For guidance on HTML style, checkout @mdo's Code Guide.