From 5d40cec3d38b32abc6c71f5f83a9f264743c7c2e Mon Sep 17 00:00:00 2001 From: Jason Rosa Date: Tue, 14 Apr 2020 11:37:55 -0400 Subject: [PATCH] Sentence casing headers in style guide --- STYLEGUIDE.md | 166 +++++++++++++++++++++++++------------------------- 1 file changed, 83 insertions(+), 83 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 543c3bdbe..b866584b5 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -1,30 +1,30 @@ -# Style Guide +# Style guide The style guide for the HubSpot CMS boilerplate. Please use this style guide as a reference when making pull requests to the [cms-theme-boilerplate](https://github.com/HubSpot/cms-theme-boilerplate/blob/master/STYLEGUIDE.md) repository. -## Table of Contents +## Table of contents - [HTML](#html) - [HubL](#hubl) - [CSS](#css) - [Javascript](#javascript) -- [File Structure](#file-structure) -- [Module Structure](#module-structure) -- [Template Structure](#template-structure) -- [Theme Structure](#theme-structure) +- [File structure](#file-structure) +- [Module structure](#module-structure) +- [Template structure](#template-structure) +- [Theme structure](#theme-structure) --- ## HTML -### HTML Best Practices +### HTML best practices 1. Two elements should never contain the same `id`. 2. Avoid inline CSS whenever possible. 3. Avoid unnecessary parent elements/wrappers whenever possible. ```html - + Test Image - +
Test Image
@@ -37,7 +37,7 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as ### Accessibility 1. Use [semantic markup](https://developer.mozilla.org/en-US/docs/Glossary/Semantics) whenever possible. ```html - +
@@ -57,7 +57,7 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as
- +
@@ -81,58 +81,58 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as 3. Use the `tabindex="0"` attribute to allow elements besides links and forms to recieve keyboard focus. Use the `tabindex="-1"` attribute to allow elements besides links and forms to receive programattic focus, meaning focus that can be set to the element through scripting. You can read [more about this topic here](https://webaim.org/techniques/keyboard/tabindex). 4. Use [aria attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) and [landmarks](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics#SignpostsLandmarks) when appropriate. -### HTML Code Formatting +### HTML code formatting 1. Write tag names, attributes, and values in lowercase.
-**Good Example:**
+**Good example:**
``
2. Avoid spaces around attribute equal signs.
-**Good Example:**
+**Good example:**
`href="/test.html"`
-**Bad Example:**
+**Bad example:**
`href = "/test.html"`
3. Use double quotation marks for attribute values.
-**Good Example:**
+**Good example:**
`alt="Cheese wheel"`
-**Bad Example:**
+**Bad example:**
`alt='Cheese wheel'`
4. Remove trailing whitespace.
-**Good Example:**
+**Good example:**
`

Here is a paragraph

`
-**Bad Example:**
+**Bad example:**
`

Here is a paragraph

___`
5. Avoid new lines between tag names and content. ```html - +

This is my best paragraph yet!

- +

This is my best paragraph yet!

``` 6. Use a new line for every block, list, or table element and indent their child elements. ```html - +
  • Here is a list item
- +
  • Here is a list item
``` 7. Indent tags by two spaces. 8. Boolean attributes: - When adding Boolean attributes to elements, be sure their placement is at the end of the element tag for optimal legibility. - Booleans do not need a declared value, only the name of the boolean is necessary for a "true" value to occur.
-**Good Example:**
+**Good example:**
``
-**Bad Example:**
+**Bad example:**
`"`
9. Use comments where appropriate to make it easier for another developer to understand your HTML. @@ -143,10 +143,10 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as - `
` over `
` 12. Omit type attributes for stylesheets and scripts. ```html - + - + ``` @@ -154,17 +154,17 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as ## HubL -### HubL Code Formatting +### HubL code formatting 1. HubL variables should have a space between the brackets on either side of the variable name.
-**Good Example:**
+**Good example:**
`{{ variable }}`
-**Bad Example:**
+**Bad example:**
`{{variable}}`
2. HubL filters should be added directly following a statement or expression.
-**Good Example:**
+**Good example:**
`{{ variable|filter }}`
-**Bad Example:**
+**Bad example:**
`{{ variable | filter }}`
3. Use single quotation marks for HubL. @@ -181,13 +181,13 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as ## CSS -### CSS Best Practices +### CSS best practices 1. Use a consistent box model style for the entire document. 2. Avoid float and clearfixes whenever possible (flex is preferred). 3. Avoid overloading selectors if you don't have to.
-**Good Example:**
+**Good example:**
`.featured-image { }`
-**Bad Example:**
+**Bad example:**
`div.wrapper div.wrapper-inner img.featured-image { }`
4. Avoid `!important` tags whenever possible. @@ -209,7 +209,7 @@ The style guide for the HubSpot CMS boilerplate. Please use this style guide as } ``` -### Vertical Rhythm +### Vertical rhythm Responsive vertical rhythm is a CSS pattern that we use on the HubSpot CMS boilerplate. [This article](https://zellwk.com/blog/responsive-vertical-rhythm/) explains the concept in more detail. Below is a quick example of how line-height and margins should match in order to create this consistent spacing. ```css /* set line height on html */ @@ -223,10 +223,10 @@ p { } ``` -### CSS Code Formatting +### CSS code formatting 1. CSS declarations should be alphabetized. ```css -/* Good Example */ +/* Good example */ .css-class { color: red; height: 200px; @@ -234,7 +234,7 @@ p { width: 10px; } -/* Bad Example */ +/* Bad example */ .css-class { width: 10px; height: 200px; @@ -282,13 +282,13 @@ When utilizing these classnames in CSS, the following code is an example of how 3. Use single quotation marks for CSS. 4. End every declaration with a semicolon. ```css -/* Good Example */ +/* Good example */ .css-class { color: #000; text-decoration: none; } -/* Bad Example */ +/* Bad example */ .css-class { color: #000; text-decoration: none @@ -296,12 +296,12 @@ When utilizing these classnames in CSS, the following code is an example of how ``` 5. Use shorthand properties where available to keep code terse. ```css -/* Good Example */ +/* Good example */ .css-class { padding: 5px 10px 10px; } -/* Bad Example */ +/* Bad example */ .css-class { padding-top: 5px; padding-bottom: 10px; @@ -310,76 +310,76 @@ When utilizing these classnames in CSS, the following code is an example of how } ``` 6. Use leading 0's before values.
-**Good Example:**
+**Good example:**
`animation-duration: 0.5s;`
-**Bad Example:**
+**Bad example:**
`animation-duration: .5s;`
7. Separate selectors and declarations by new lines. ```css -/* Good Example */ +/* Good example */ .css-class { color: #000; margin-top: 10px; } -/* Bad Example */ +/* Bad example */ .css-class { color: #000; margin-top: 10px; } ``` 8. Indent all block conent. ```css -/* Good Example */ +/* Good example */ .css-class { font-size: 20px; padding: 10px; } -/* Bad Example */ +/* Bad example */ .css-class { font-size: 20px; padding: 10px; } ``` 9. Always use a single space between the property and value.
-**Good Example:**
+**Good example:**
`float: none;`
-**Bad Example:**
+**Bad example:**
`float:none;`
10. When grouping together, Selectors should be placed on their own lines and separated by a comma. ```css -/* Good Example */ +/* Good example */ .css-class, .css-class-two { border: 1px solid #000; } -/* Bad Example */ +/* Bad example */ .css-class, .css-class-two { border: 1px solid #000; } ``` 11. One space should be used between selectors and the opening brace of the declaration block. In addition, closing braces should be placed on a new line by themselves. ```css -/* Good Example */ +/* Good example */ .css-class { font-weight: 700; } -/* Bad Example */ +/* Bad example */ .css-class{ font-weight: 700;} ``` 12. Include a space after each comma in separated property values.
-**Good Example:**
+**Good example:**
`background-color: rgba(0, 0, 0, 0.5);`
-**Bad Example:**
+**Bad example:**
`background-color: rgba(0,0,0,0.5);`
13. Don't include the unit identifier for length values that are set to 0.
-**Good Example:**
+**Good example:**
`margin-top: 0;`
-**Bad Example:**
+**Bad example:**
`margin-top: 0px;`
14. Media queries should be written directly next to the non-media queried element. @@ -395,12 +395,12 @@ padding: 10px; ``` 15. Avoid duplicating style declarations if they'll be inherited or overridden. ```css -/* Good Example */ +/* Good example */ li + li { visibility: hidden; } -/* Bad Example */ +/* Bad example */ li { visibility: hidden; } @@ -421,7 +421,7 @@ li:first-child { ## Javascript We generally use ES5 as it is more compatibile with older browsers such as Internet Explorer 11. ES6 can be used if you're using a build step with a transpiler like [Babel](https://babeljs.io/). We don't use jQuery. -### JavaScript Best Practies +### JavaScript best practies 1. Leverage [event bubbling](https://www.sitepoint.com/javascript-tooling-evolution-modern-developers-guide/) whenever possible. 2. Functions should return new objects instead of mutating existing ones. Here is a [good reference](https://alistapart.com/article/why-mutation-can-be-scary/) on the problems with mutating objects. 3. Minimize dependencies. @@ -429,17 +429,17 @@ We generally use ES5 as it is more compatibile with older browsers such as Inter ### Accessibility 1. It is important to remember that not everyone has JavaScript enabled on their browser so the website should still generally function properly if JavaScript is disabled (add CSS fallbacks when possible). -### JavaScript Code Formatting +### JavaScript code formatting 1. Use single quotation marks for JavaScript and JSON.
-**Good Example:**
+**Good example:**
`var navToggle = document.querySelector('#nav-toggle');`
-**Bad Example:**
+**Bad example:**
`var navToggle = document.querySelector("#nav-toggle");`
2. Variable and function names should clearly indicate their purpose.
-**Good Example:**
+**Good example:**
`var navToggle = document.querySelector('#nav-toggle');`
-**Bad Example:**
+**Bad example:**
`var z = document.querySelector("#nav-toggle");`
3. Use comments where appropriate to make it easier for another developer to understand your JavaScript. @@ -448,17 +448,17 @@ We generally use ES5 as it is more compatibile with older browsers such as Inter ## File Structure -### General Naming Conventions: +### General naming conventions: 1. Avoid special characters and spaces in file names. 2. File names should be clear and descriptive; providing immediate insight of their intended use or content at first glance. 3. Use lower case names separated by hyphens. 4. Use an underscore at the start of a style sheet if it isn't directly included in a template. ``` -**Good Examples:** +**Good examples:** home.html _dnd-areas.css -**Bad Examples:** +**Bad examples:** Home.html home!.html page-1.html @@ -466,22 +466,22 @@ dndareas.css dnd_areas.css ``` -### Asset Labeling: +### Asset labeling: 1. All assets (templates, partials, modules, module settings, theme settings) should include a label and the label should use sentence casing. 2. Template names should omit the word `page` in their file names or their related assets/code _unless_ it is the `Landing page` template. ``` -****Good Example:** +****Good example:** home.html -Bad Example:** +Bad example:** home-page.html ``` --- -## Module Structure: +## Module structure: -### General Folder Structure: +### General folder structure: ``` /module-name.module fields.json @@ -536,26 +536,26 @@ default: --- -## Template Structure: +## Template structure: -### Drag and Drop Object Formatting: +### Drag and drop object formatting: 1. Opening and closing tags should be on their own line to increase legibility. 2. Parameters (after the `name` or `path`) should be written on their own line to increase legibility. 3. After `path`/`name` and `label`, all other parameters should be ordered alphabetically to ensure consistency and increase legibility. 4. For margin and padding parameters, the values should be ordered: top, right, bottom, left to match CSS shorthand for those properties. ```jinja -{# Good Example: #} +{# Good example: #} {% dnd_module path="../modules/button", button_link="#", button_text="Get Started" %} {% end_dnd_module %} -{# Bad Example: #} +{# Bad example: #} {% dnd_module path="../modules/button", button_text="Get Started", button_link="#" %}{% end_dnd_module %} ``` -### Template Meta Data: +### Template meta data: The top of each template should include a YAML code block formatted to match the example below. Blog and system templates should have their `label`s prefixed with the theme's name. Ex. `label: Boilerplate - blog post`. Requirements for screenshots can be found below at [Template Screenshots](#template-screenshots). @@ -569,7 +569,7 @@ Requirements for screenshots can be found below at [Template Screenshots](#templ --> ``` -### Template Screenshots: +### Template screenshots: Screenshots should be taken for all templates and linked in the template's meta data section (see [Template Meta Data](#template-meta-data) above). The process for creating a screenshot is: - Take a full page screenshot of the template @@ -581,7 +581,7 @@ Screenshots should be taken for all templates and linked in the template's meta --- -## Theme Structure +## Theme structure ### Theme.json The `theme.json` file should be structured like the code below. The file should include a `label` to match the theme's name, a `preview_path` to set the theme's default preview template, and a `screenshot_path` to set the theme's preview image which displays when a user selects which theme they want to use. The image used for the `screenshot_path` should be stored under the `/images/template-previews/` folder.