├── .github
    ├── CODEOWNERS
    ├── CONTRIBUTING.md
    └── pull_request_template.md
├── CHANGELOG.md
├── README.md
├── accessibility
    └── README.md
├── assets
    └── logo.png
├── css
    └── README.md
├── frame
    ├── README.md
    ├── css
    │   └── README.md
    ├── html
    │   └── README.md
    ├── liquid
    │   └── README.md
    └── vs-code
    │   └── README.md
├── html-vue-template
    └── README.md
├── javascript-vue-sfc
    └── README.md
├── liquid
    ├── README.md
    └── setting-states.md
└── vs-code
    └── README.md


/.github/CODEOWNERS:
--------------------------------------------------------------------------------
 1 | # GitHub code owners file
 2 | # Each line is a file pattern followed by one or more owners.
 3 | # Code owners are will be requested for review when someone opens a pull request.
 4 | # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 5 | 
 6 | # Global owners.
 7 | # Space separated list of GitHub usernames.
 8 | # Remove comment to enable.
 9 | * @craigsbaldwin
10 | 
11 | # Example of a JavaScript file owner.
12 | # The last matching pattern takes the most precedence.
13 | # *.js @js-owner
14 | 


--------------------------------------------------------------------------------
/.github/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # 👩‍💻 Contributing
2 | 
3 | Please ensure you are familiar with the below documentation before contributing to the repository:
4 | 
5 | * [Coding guidelines](https://github.com/we-make-websites/wmw-coding-guidelines/blob/main/README.md)
6 | * [Branch naming convention](https://www.notion.so/wemakewebsites/Naming-Conventions-3b426d0d1f414488a45dcf76e6d469b8?pvs=4#24619e035c814fc1b1c12866f1e6d9d3)
7 | * [Commit messages convention](https://www.notion.so/wemakewebsites/Naming-Conventions-3b426d0d1f414488a45dcf76e6d469b8?pvs=4#39baa06684a943849be83ab75dd8be6e)
8 | * [Code review guidance](https://www.notion.so/wemakewebsites/Code-Reviews-5ab62ce82fc94cafa30128332279beea)
9 | 


--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
 1 | # What are you trying to accomplish with this PR?
 2 | 
 3 | <!--
 4 | Provide a detailed description of the objective of this pull request.
 5 | Are you fixing a typo? Updating a rule? Or adding a completely new rule?
 6 | Use the appropriate PR labels.
 7 | -->
 8 | 
 9 | **Task:** <!-- Jira task ID, e.g. CANVAS-422 -->
10 | 
11 | # Checklist
12 | For contributors (tick when done):
13 | 
14 | - [ ] New content has been spell checked
15 | - [ ] New rules have code examples
16 | - [ ] New rules have been added to their respective table of contents
17 | - [ ] Code examples feature valid and guideline compliant code
18 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # 📏 Coding Guidelines Changelog
  2 | 
  3 | ## 3.1.0 - 2024-01-11
  4 | 
  5 | * Added _.github/_ folder
  6 | * Home - General updates to _README.md_
  7 | * CSS - Updated Property order rule
  8 | * CSS - Updated Mobile first rule
  9 | * CSS - Updated Responsive banner padding and `aspect-ratio` rules
 10 | 
 11 | ## 3.0.1 - 2023-08-30
 12 | 
 13 | * CSS - Fixed unclosed codeblock
 14 | 
 15 | ## 3.0.0 - 2023-08-23
 16 | 
 17 | * Added accessibility section
 18 | 
 19 | ## 2.8.0 - 2023-08-09
 20 | 
 21 | * CSS - Added `height` & `width` rules
 22 | * CSS - Expanded `margin` & `padding` rules with variable calculation details
 23 | * CSS - Re-ordered rules to be in alphabetical order
 24 | * CSS - Moved spacing category rules into formatting category
 25 | 
 26 | ## 2.7.0 - 2023-05-03
 27 | 
 28 | * CSS - Updated to reflect new rules
 29 | 
 30 | ## 2.6.1 - 2023-04-11
 31 | 
 32 | * CSS - Fixed title linking
 33 | 
 34 | ## 2.6.0 - 2022-10-12
 35 | 
 36 | * General proof reading updates
 37 | * Updated Canvas and Frame to be Title case
 38 | * Removed permalinks as GitHub adds them automatically
 39 | * VS Code - Updated recommended extensions and settings
 40 | 
 41 | ### JavaScript & Vue SFC
 42 | * Add if conditions, newlines, passing parameters, and whitespace rules
 43 | * Updated array and indents rules
 44 | 
 45 | ## 2.5.0 - 2022-06-21
 46 | 
 47 | * VS Code - Updated recommended extensions to match Canvas
 48 | 
 49 | ## 2.4.1 - 2022-04-06
 50 | 
 51 | * CSS - Fixed title linking
 52 | 
 53 | ## 2.4.0 - 2022-04-06
 54 | 
 55 | * Home - Updated Canvas naming
 56 | * CSS - General updates
 57 | * CSS - Fixed incorrect usage of `margin` and `padding`
 58 | * HTML - General updates
 59 | * Liquid - General updates
 60 | * Liquid - Updated filter guidelines
 61 | * Liquid - Updated commenting guidelines
 62 | * JavaScript & Vue SFC - General updates
 63 | 
 64 | ## 2.3.0 - 2022-04-05
 65 | 
 66 | * Liquid - Added order for schema settings
 67 | * Liquid - Updated conditional statements
 68 | * Liquid - Added setting states page linked from conditional statements
 69 | * JavaScript & Vue SFC - Updated title linking
 70 | 
 71 | ## 2.2.0 - 2022-04-05
 72 | 
 73 | * JavaScript & Vue SFC - Added Vue SFC order rule
 74 | * JavaScript & Vue SFC - Added variable rules
 75 | 
 76 | ## 2.2.0 - 2021-11-03
 77 | 
 78 | * HTML - Added attribute casing rule
 79 | * JavaScript & Vue SFC - Updated array rules
 80 | 
 81 | ## 2.1.0 - 2021-10-26
 82 | 
 83 | * VS Code - Removed bracket colorizer extension
 84 | * VS Code - Updated recommended settings to use native bracket colourisation and set stylelint to lint SCSS
 85 | 
 86 | ## 2.0.1 - 2021-08-02
 87 | 
 88 | * JavaScript & Vue SFC - Added note about automatic indenting by `eslint`
 89 | * Changelog – Fixed dates
 90 | 
 91 | ## 2.0.0 - 2021-07-29
 92 | 
 93 | * Added Canvas rules
 94 | * Moved Frame rules into separate folder
 95 | 
 96 | ## 1.2.4 - 2020-12-01
 97 | 
 98 | * VS Code - Updated extensions list
 99 | 
100 | ## 1.2.3 - 2019-12-09
101 | 
102 | * HTML - Replaced `{% include %}` with `{% render %}`
103 | * Liquid - Replaced `{% include %}` with `{% render %}`
104 | 
105 | ## 1.2.2 - 2019-12-09
106 | 
107 | * Home - Added VS Code section
108 | * VS Code - Details recommended extensions and settings
109 | 
110 | ## 1.2.1 – 2019-10-03
111 | 
112 | * CSS – Added proper names for variable naming convention
113 | * CSS – Removed fallback rule for BEM
114 | * HTML – Added rule for `aria-` attributes
115 | * HTML – Made examples make more sense
116 | * HTML – Added attribute values rule
117 | 
118 | ## 1.2.0 – 2019-09-25
119 | 
120 | * HTML – Added example of multi-line attribute
121 | * Liquid – Re-organised structure
122 | * Liquid – Added section and snippet naming conventions and file structure
123 | 
124 | ## 1.1.13 – 2019-08-08
125 | 
126 | * All - Added navigational aids
127 | * HTML – Change attributes rule name
128 | * Liquid – Added split characters rule
129 | 
130 | ## 1.1.12 – 2019-08-07
131 | 
132 | * Changelog – Fixed version numbering
133 | 
134 | ## 1.1.11 – 2019-08-01
135 | 
136 | * Liquid – Fixed issue with wording
137 | 
138 | ## 1.1.10 – 2019-07-11
139 | 
140 | * Liquid – Updated spacing & line character limits rule
141 | * Liquid – Standardised `{% if %}` tag language
142 | 
143 | ## 1.1.9 – 2019-07-10
144 | 
145 | * HTML – Updated title of the spacing rule
146 | * Liquid – Updated `{% include %}` and spacing rule
147 | 
148 | ## 1.1.8 – 2019-07-09
149 | 
150 | * HTML – Fixed indenting example
151 | * Liquid – Corrected typo
152 | 
153 | ## 1.1.7 – 2019-07-03
154 | 
155 | * Liquid – Added tag naming rule, updated other rules to use tag naming convention
156 | 
157 | ## 1.1.6 – 2019-06-26
158 | 
159 | * Changelog – Updated order of changelog items
160 | * Home – Updated home with new content
161 | * HTML – Updated spacing rule
162 | * Liquid – Added `{% include %}` rule
163 | 
164 | ## 1.1.5 – 2019-06-20
165 | 
166 | * Home – Improving home content
167 | 
168 | ## 1.1.4 – 2019-06-20
169 | 
170 | * All – Added back to TOC links at the end of each section
171 | * HTML – Added `<div>` or `<span>` rule
172 | * HTML – Updated spacing and attributes rules
173 | 
174 | ## 1.1.3 – 2019-06-20
175 | 
176 | * CSS – Fixed broken links
177 | * Home – Enabled HTML and Liquid links
178 | * HTML – Updated spacing rule
179 | * Liquid – Added rules for inline if statements and conditional spacing
180 | * Liquid – Fixed broken links
181 | * Liquid – Re-organised some existing rules
182 | 
183 | ## 1.1.2 – 2019-06-14
184 | 
185 | * Home – Added introductory text
186 | * Liquid – Added rules for language strings and variable assigning
187 | * Liquid – Fixed broken links in TOC
188 | * Liquid – Grouped variables rules together
189 | 
190 | ## 1.1.1 – 2019-06-12
191 | 
192 | * Liquid – Added rules for conditional settings, DRY, and snippets
193 | * Liquid – Updated whitespace control rule
194 | * Liquid – Corrected terminology
195 | 
196 | ## 1.1.0 – 2019-06-11
197 | 
198 | * CSS – Added introductory comments guidelines
199 | * CSS – Corrected typo
200 | * HTML – Began work on guidelines
201 | * Liquid – Began work on guidelines
202 | 
203 | ## 1.0.3 – 2019-04-23
204 | 
205 | * CSS – Initial release of updated guidelines
206 | * CSS – Minor formatting and naming fixes
207 | * JS – Linked to Shopify's guidelines


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | <p align="center"><img src="https://raw.githubusercontent.com/we-make-websites/wmw-coding-guidelines/master/assets/logo.png" alt="We Make Websites" width="170"></p>
 2 | 
 3 | # 📏 Coding Guidelines
 4 | 
 5 | Standards, guidelines, and best practice when working on our Canvas framework.
 6 | 
 7 | Updates to Basis and projects using Basis Adapter must also follow these guidelines.
 8 | 
 9 | For Frame projects [follow these guidelines](frame/README.md).
10 | 
11 | ## Table of contents
12 | 
13 | * [HTML & Vue `template`](html-vue-template/README.md)
14 | * [Liquid](liquid/README.md)
15 | * [CSS/SCSS](css/README.md)
16 | * [JavaScript & Vue SFC](javascript-vue-sfc/README.md)
17 | * [Accessibility](accessibility/README.md)
18 | * [VS Code](vs-code/README.md)
19 | 
20 | ## Why do we need guidelines?
21 | 
22 | When working on large, long-running projects, with dozens of developers of differing specialities and abilities, it is important that we all work in a unified way in order to:
23 | 
24 | * Keep the code base maintainable
25 | * Keep code transparent, sane, and readable
26 | * Keep the code base scalable
27 | * Maintain the code base's performance
28 | 
29 | ## Applying the guidelines
30 | 
31 | When you are writing new code you are expected to maintain the guidelines, if you update an existing feature you are expected to update any non-adhering code that you interact with or change. This means you are not expected to fix the whole file when adding new functionality, just the code you write or change.
32 | 
33 | Assuming you've followed [project setup](https://we-make-websites.gitbook.io/canvas/guides/project-setup) then your JS, SCSS, and Vue files will be formatted by `eslint --fix` and `stylelint --fix` when you save a supported file. Other `eslint` and `stylelint` errors will be flagged when committing your changes.
34 | 
35 | You will have to manually apply the guidelines to HTML and Liquid as there is no linter available. Certain Vue and SCSS rules must also be applied manually as their respective linters don't support them.
36 | 
37 | ## Can I contribute to the guidelines?
38 | 
39 | Please branch from `main` and submit a pull request to the relevant code owner for review.
40 | 
41 | See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more details on process and code quality when contributing.
42 | 


--------------------------------------------------------------------------------
/accessibility/README.md:
--------------------------------------------------------------------------------
  1 | # Accessibility
  2 | 
  3 | These rules apply to all Liquid, HTML, and Vue `<template>` code.
  4 | 
  5 | The examples given here will mainly be written in Vue, but the same rules apply for vanilla JS code bases.
  6 | 
  7 | ## Table on contents
  8 | 
  9 | * [Native Elements](#native-elements)
 10 | * [Keyboard Support](#keyboard-support)
 11 | * [Accessible Text](#accessible-text)
 12 | * [Alt Text](#alt-text)
 13 | * [Element IDs](#element-ids)
 14 | * [Additional Resources](#additional-resources)
 15 | 
 16 | [← Back to homepage](../README.md)
 17 | 
 18 | ## Native Elements
 19 | 
 20 | * [Use `<button>` elements for clickable items](#use-button-element-for-clickable-items)
 21 | * [Don't use `<a>` elements where a `<button>` would be better](#dont-use-a-elements-where-a-button-would-be-better)
 22 | * [Use input events rather than wrapping click events](#use-input-events-rather-than-wrapping-click-events)
 23 | 
 24 | ### Use `<button>` element for clickable items
 25 | 
 26 | #### Don't
 27 | 
 28 | ```vue
 29 | <div
 30 |   class="dropdown-menu__input"
 31 |   @click="toggleMenu"
 32 | >
 33 |   <span v-text="label">
 34 |   <icon-chevron-down />
 35 | </div>
 36 | 
 37 | <responsive-image @click="handleImageClick" />
 38 | 
 39 | <a @click="toggleItem">
 40 |   Click here
 41 | </a>
 42 | ```
 43 | 
 44 | #### Do
 45 | 
 46 | ```vue
 47 | <button
 48 |   class="dropdown-menu__input"
 49 |   @click="toggleMenu"
 50 | >
 51 |   <span v-text="label">
 52 |   <icon-chevron-down />
 53 | </button>
 54 | 
 55 | <button @click="handleImageClick">
 56 |   <responsive-image />
 57 | </button>
 58 | 
 59 | ```
 60 | 
 61 | * Prefer using native `<button>` element instead of adding click event handlers to non-interactive elements like `<div>`
 62 | 
 63 | #### Why
 64 | 
 65 | * The native `<button>` element comes with accessible defaults out of the box such as:
 66 |   * Keyboard interaction (buttons can be triggered with `Space` or `Enter` keys)
 67 |   * Keyboard focusable
 68 |   * Buttons are declared correctly to screen-readers
 69 |   * A button's interactivity can be natively disabled with the `disabled` attribute
 70 | * Re-creating all of these out of the box defaults on a `<div>` or other element would require additional attributes and event handlers which results in more code to write and more code shipped to the user - Using native elements has performance benefits too
 71 | * E.g. here's a comparison of using a `<div>` element vs a `<button>` element:
 72 | 
 73 | ```vue
 74 | <!-- Bad -->
 75 | <div
 76 |   role="button"
 77 |   tabindex="0"
 78 |   @click="handleClick"
 79 |   @keydown="handleKeyDown"
 80 | >
 81 |   Click me
 82 | </div>
 83 | 
 84 | <!-- Good -->
 85 | <button @click="handleClick">
 86 |   Click me
 87 | </button>
 88 | ```
 89 | 
 90 | * Note: The `<div>` in the example does not include additional features that the `<button>` comes with, such as indicating a `disabled` state and the code for `handleKeyDown` so that it only responds to Enter and Tab keypresses
 91 | 
 92 | ### Don't use `<a>` elements where a `<button>` would be better
 93 | 
 94 | #### Don't
 95 | 
 96 | ```vue
 97 | <a @click="toggleItem">
 98 |   Click here
 99 | </a>
100 | 
101 | <a
102 |   href="#"
103 |   @click.prevent="doSomething"
104 | >
105 |   Do Something
106 | </a>
107 | ```
108 | 
109 | #### Do
110 | 
111 | ```vue
112 | <button @click="toggleItem">
113 |   Click here
114 | </button>
115 | 
116 | <button @click.prevent="doSomething">
117 |   Do something
118 | </button>
119 | ```
120 | 
121 | * If an element is not linking somewhere, it's better to use a `<button>` element instead
122 | * `<a>` tags should not be used without a `href` attribute or with blank or javascript `href` attribute
123 | 
124 | #### Exceptions
125 | * You should consider using a `<a>` element in cases where clicking on the element updates the URL and visiting that URL directly would display a different page
126 | * An example would be Colour Swatches, where clicking on a swatch would update the current page and load in a new product in Vue, but the data is fetched from a separate product with its own URL
127 | * The benefit here is that web crawlers can read these links to discover the other pages
128 | 
129 | ```vue
130 | <a
131 |   :href="`/products/${swatchProduct.handle}`"
132 |   @click.prevent="handleSwatchClick"
133 |   v-text="swatchProduct.color"
134 | />
135 | ```
136 | 
137 | ### Use input events rather than wrapping click events
138 | 
139 | #### Don't
140 | 
141 | ```vue
142 | <li
143 |   v-for="item in items"
144 |   :key="item.id"
145 |   @click="filter(item.value)"
146 | >
147 |   <input
148 |     :id="item.id"
149 |     :checked="item.active"
150 |     type="checkbox"
151 |     :value="item.value"
152 |   >
153 | 
154 |   <label
155 |     :for="item.id"
156 |     v-text="item.label"
157 |   >
158 | </li>
159 | ```
160 | 
161 | #### Do
162 | 
163 | ```vue
164 | <li
165 |   v-for="item in items"
166 |   :key="item.id"
167 | >
168 |   <input
169 |     :id="item.id"
170 |     :checked="item.active"
171 |     type="checkbox"
172 |     :value="item.value"
173 |     @change="filter($event.target.value)"
174 |   >
175 | 
176 |   <label
177 |     :for="item.id"
178 |     v-text="item.label"
179 |   />
180 | </li>
181 | ```
182 | 
183 | * Instead of adding a click event to an `input` element's parent, use the native `input` or `change` events
184 | 
185 | [ꜛ Back to TOC](#table-of-contents)
186 | 
187 | ## Keyboard Support
188 | 
189 | * [Test keyboard focus](#test-keyboard-focus)
190 | * [Test keyboard tab order](#test-keyboard-tab-order)
191 | * [Focus Trap](#focus-trap)
192 | 
193 | ### Test keyboard focus
194 | * Ensure that interactive elements can be focussed and activated using a keyboard
195 | * Ensure that functionality that supports mouse interactions (click, mousedown, mouseleave etc) have suitable keyboard-accessible alternatives
196 | 
197 | ### Test keyboard tab order
198 | * Ensure that keyboard focus order is correct
199 |   * The order that items are focussed when tabbing should match the visual order of the elements on the page
200 |   * Try to ensure that the order of elements in the DOM matches the visual order on the site
201 | * Exceptions can be made here when the order changes responsively, e.g. when the order is correct on mobile screen sizes
202 | 
203 | ### Focus Trap
204 | 
205 | * Use a focus trap when opening overlays so that a keyboard user is only able to tab between elements inside the overlay
206 | * Ensure that the focus trap is cleared when an overlay is closed
207 | * Ensure that the focus trap is updated when the overlay state changes
208 |   * Example: if you have a multi-tiered navigation, ensure that the focus trap updates as the user navigates between tiers
209 |   * Example: if you have a search overlay and the results update as you type, ensure that focus trap updates as the content changes
210 | * Focus trapping can be achieved with the `focusTrap` and `previousElement` helpers in the `accessibility.js` store - see [Canvas Gitbook - accessibility.js](https://we-make-websites.gitbook.io/canvas/features/vuex-stores/accessibility.js)
211 | 
212 | #### Why
213 | 
214 | * Using a focus trap prevents users from tabbing to elements outside of the overlay element, preventing an issue where the user might not know which element they are focussed on
215 | 
216 | [ꜛ Back to TOC](#table-of-contents)
217 | 
218 | ## Accessible Text
219 | 
220 | * [Ensure that `input` elements have corresponding `label` elements](#ensure-that-input-elements-have-corresponding-label-elements)
221 | * [Ensure interactive elements have accessible text](#ensure-interactive-elements-have-accessible-text)
222 | * [Ensure correct usage of `aria-labelledby` and `aria-label`](#ensure-correct-usage-of-aria-labelledby-and-aria-label)
223 | * [Ensure correct usage of `aria-labelledby` on `<section>` elements](#ensure-correct-usage-of-aria-labelledby-on-section-elements)
224 | 
225 | ### Ensure that `input` elements have corresponding `label` elements
226 | 
227 | #### Don't
228 | 
229 | ```html
230 | <input
231 |   id="newsletter-email"
232 |   name="email"
233 |   placeholder="Enter your email"
234 |   type="email"
235 | >
236 | ```
237 | 
238 | #### Do
239 | 
240 | ```html
241 | <label for="newsletter-email">
242 |   Enter your email
243 | </label>
244 | 
245 | <input
246 |   id="newsletter-email"
247 |   name="email"
248 |   placeholder="Enter your email"
249 |   type="email"
250 | >
251 | ```
252 | 
253 | * Ensuring that your `input` has a corresponding `label` element helps to describe the purpose of the input and can provide instructions for it for all users
254 | * A `label` should be used even when the input has a `placeholder` attribute
255 |   * Assistive technology, such as screen-readers do not treat placeholder text as labels, so a `placeholder` should be used alongside a label, not instead of a label
256 | * In some cases, a site's design may show inputs without visible labels, sometimes this may be because other elements on the page give the input some context - for example a search text input placed directly next to a 'Search' button
257 |   * If a input does not have a visible label, a `<label>` element should still be added for the benefit of screen readers
258 |   * A label can be hidden visually by adding the `visually-hidden` class to the `label`
259 | 
260 | ```html
261 | <!-- Label will be available to assistive technology, but visually hidden -->
262 | <label
263 |   class="visually-hidden"
264 |   for="search"
265 | >
266 |   Search the site
267 | </label>
268 | 
269 | <input
270 |   id="search"
271 |   name="search"
272 |   type="text"
273 | >
274 | ```
275 | 
276 | ### Ensure interactive elements have accessible text
277 | 
278 | #### Don't
279 | 
280 | ```vue
281 | <a
282 |   class="site-logo"
283 |   href="/"
284 | >
285 |   <brand-logo />
286 | </a>
287 | 
288 | <button
289 |   type="button"
290 |   @click="openMenuDrawer"
291 | >
292 |   <icon-menu />
293 | </button>
294 | 
295 | <a href="/account">
296 |   <icon-account />
297 | </a>
298 | 
299 | <a href="/sale">
300 |   <!-- Image containing embedded text about a 10% off sale -->
301 |   <img src="10-off-promo-image.jpg">
302 | </a>
303 | ```
304 | 
305 | #### Do
306 | 
307 | ```vue
308 | <a
309 |   class="site-logo"
310 |   href="/"
311 | >
312 |   <brand-logo />
313 | 
314 |   <span class="visually-hidden">
315 |     My Shop Name
316 |   </span>
317 | </a>
318 | 
319 | <button
320 |   type="button"
321 |   @click="openMenuDrawer"
322 | >
323 |   <icon-menu />
324 | 
325 |   <span class="visually-hidden">
326 |     Toggle Menu
327 |   </span>
328 | </button>
329 | 
330 | <a href="/account">
331 |   <icon-account />
332 | 
333 |   <span class="visually-hidden">
334 |     Account
335 |   </span>
336 | </a>
337 | 
338 | <a href="/sale">
339 |   <!-- Image containing embedded text about a 10% off sale -->
340 |   <img src="10-off-promo-image.jpg" alt="Get 10% off">
341 | </a>
342 | ```
343 | 
344 | * When using `<button>` or `<a>` elements containing SVG elements, ensure that accessible text is also included
345 |   * If the text should not be visible, the `visually-hidden` class can be used
346 | * If a `<button>` or `<a>` contains a `<img>` element - ensure that there is either appropriate `alt` text on the image, or add a supporting `visually-hidden` span with appropriate text
347 |   * Avoid using both `alt` and `visually-hidden` text for the same element, otherwise screen readers will read out possibly duplicate or irrelevant content
348 |   * Setting an empty `alt` text is fine when using `visually-hidden` text - see [Alt Text](#alt-text) for more details
349 | 
350 | ### Ensure correct usage of `aria-labelledby` and `aria-label`
351 | 
352 | * The `aria-labelledby` and `aria-label` attributes provide another method for adding labels to elements
353 | * These are alternatives to using a `visually-hidden` element showcased in the examples above
354 | 
355 | #### `aria-labelledby`
356 | 
357 | * `aria-labelledby` can be used to label an element based on the text content of another existing element by it's unique `id`
358 | * If a heading is present inside a region, this could be a good candidate for `aria-labelledby`
359 | 
360 | ```html
361 | <section aria-labelledby="template-title">
362 |   <h1 id="template-title">
363 |     Title for the section
364 |   </h1>
365 | 
366 |   <!-- Other content -->
367 | </section>
368 | ```
369 | 
370 | * In many cases, elements get accessible names from either their inner content (e.g. `<button>`, `<a>` or `<td>` elements), or from associated content (e.g. an `<input>` and it's `<label>` element), so there are many cases you won't need to reach for `aria-labelledby`
371 | * Ensure that the element referenced by `aria-labelledby` exists on the page
372 |   * If the referenced element is missing, screen readers will still read out the the other text content contained in the element, but users may be missing out on the additional context that the referenced element might be adding
373 | * When using `aria-labelledby` in a component, consider whether the element you are referencing exists inside the component's template code
374 |   * If the element you are targeting with `aria-labelledby` is stored in another component or snippet, you may not be able to guarantee that it will always be on the page
375 |   * In this case, opt to use `<span class="visually-hidden">` or `aria-label` instead
376 | * There are some caveats to be aware of when using `aria-labelledby` on `<section>` elements - See [Ensure correct usage of `aria-labelledby` on `<section>` elements](#ensure-correct-usage-of-aria-labelledby-on-section-elements)
377 | * Additional documentation available at [MDN - aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby)
378 | 
379 | #### `aria-label`
380 | * `aria-label` is another approach for labelling elements, and can be used when there is no visible element in the DOM that can be used directly as a label or referenced with `aria-labelledby`
381 | * **Use `aria-label` with caution** - if adding `visually-hidden` text is possible, this is preferred instead
382 |   * `aria-label` has a rocky history with screen reader support with certain combinations of screen readers and browsers, whereas printed text is always read out (unless `display: none` or `visibility: hidden` styles or the `hidden` or `aria-hidden` attributes are used)
383 |   * Using `visually-hidden` text that is rendered in the DOM can also benefit users users that are translating the language of your site as these services are often better at detecting `visually-hidden` text then they are `aria-label` attributes
384 |   * See [this blog post from 2020](https://gomakethings.com/revisting-aria-label-versus-a-visually-hidden-class/)
385 | * Examples of using this are similar to adding a `<span class="visually-hidden">` element
386 | 
387 | ```vue
388 | <button
389 |   type="button"
390 |   aria-label="Toggle Menu"
391 |   @click="openMenuDrawer"
392 | >
393 |   <icon-menu />
394 | </button>
395 | 
396 | <a
397 |   href="/account"
398 |   aria-label="Account"
399 | >
400 |   <icon-account />
401 | </a>
402 | ```
403 | 
404 | ### Ensure correct usage of `aria-labelledby` on `<section>` elements
405 | 
406 | * When a `<section>` element is given an accessible name, for example with the `aria-labelledby` or `aria-label` attribute, the element receives an implicit ARIA attribute [`role="region"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) which marks it as a [landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) for screen readers and other assistive technologies
407 | * These landmarks can then be used as another method for screen reader users to navigate around the page and understand its contents
408 | * **However, creating additional landmarks with the `<section>` element must only be done when necessary**
409 |   * Adding too many landmark roles on the page can create "noise" for screen readers and actually make the site harder to understand and use, so must be used sparingly
410 | * For Canvas projects, `aria-labelledby` should only be used on `<section>` elements that are used as the main section or main component for a page template, and not used on reusable 'sections everywhere' sections or components
411 |   * See [Main components](https://we-make-websites.gitbook.io/canvas/components/other-types/main-components) for help identifying what the main component of a template should be
412 | * The standard for main components in Canvas is that they have a `<h1 id="template-title">` element containing relevant text, with the `<section>` element given the `aria-labelledby="template-title"` attribute
413 | * When replacing or updating one of the default Canvas main components, ensure that you still have an element with `id="template-title"` for the `aria-labelledby` attribute to reference
414 | 
415 | 
416 | [ꜛ Back to TOC](#table-of-contents)
417 | 
418 | ## Alt Text
419 | * Alt text is extremely useful for ensuring that images on the site can be used by people with various disabilities
420 | * Images can be categorised in different ways and there are some different recommendations for alt text depending on the type of image
421 | * The W3C Web Accessibility Initiative has some good resources around Images:
422 |   * [Images Tutorial](https://www.w3.org/WAI/tutorials/images/) - Outlines the different purposes an image might have and recommendations for adding accessible text
423 |   * [`alt` Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) - Provides a helpful decision tree on how to handle different situations with images, including when an empty `alt` attribute is appropriate
424 | 
425 | [ꜛ Back to TOC](#table-of-contents)
426 | 
427 | ## Element IDs
428 | 
429 | * A variety of accessibility code and functionality (such as the `label` element's `for` attribute, `aria-labelledby` and other `aria-` attributes) use the `id` attribute to reference other elements
430 |   * For example, linking a checkbox input with a label using `id`/`for` allows the user to click on the label to toggle the checkbox
431 |   * This helps make the input easier to trigger with a mouse, and also makes it possible to style custom inputs (for example custom checkboxes) by applying styles to the `<label>` element
432 | * When writing components that use the `id` attribute - ensure that the `id` will always be unique
433 |   * Avoid hard coding an `id` for an element unless you know it will only be used once
434 |   * This is particularly important when the component is designed to be re-used, for example a swatch or a line item component
435 |   * Unique IDs can be generated using passed in data, and additionally namespaces if needed
436 |   * For section type Canvas components - you could also pass the Shopify `section.id` as a prop and use that in your element `id`
437 | 
438 | ### Example of a dynamic `id` based on unique prop data
439 | 
440 | ```vue
441 | <template>
442 |   <div class="quantity-selector">
443 |     <label
444 |       class="visually-hidden"
445 |       :for="`quantity-selector-input-${lineItem.key}`"
446 |     >
447 |       Quantity
448 |     </label>
449 | 
450 |     <input
451 |       :id="`quantity-selector-input-${lineItem.key}`"
452 |       type="number"
453 |       value="1"
454 |     >
455 |   </div>
456 | </template>
457 | 
458 | <script>
459 | export default {
460 |   name: 'QuantitySelector',
461 | 
462 |   props: {
463 |     // Cart line item data from Shopify
464 |     lineItem: {
465 |       type: Object,
466 |       default: () => ({}),
467 |     },
468 |   },
469 | }
470 | </script>
471 | ```
472 | 
473 | ### Example of setting an explicit unique `id` with a `namespace` prop
474 | 
475 | ```vue
476 | <template>
477 |   <div class="variant-dropdown">
478 |     <label
479 |       class="visually-hidden"
480 |       :for="`${namespace}-variant-dropdown`"
481 |     >
482 |       Quantity
483 |     </label>
484 | 
485 |     <select :id="`${namespace}-variant-dropdown`">
486 |       <option v-for="option in options">
487 |     </select>
488 |   </div>
489 | </template>
490 | 
491 | <script>
492 | export default {
493 |   name: 'VariantDropdown',
494 | 
495 |   props: {
496 |     namespace: {
497 |       type: String,
498 |       default: '',
499 |       required: true,
500 |     },
501 |     options: {
502 |       type: Array,
503 |       default: () => [],
504 |     },
505 |   },
506 | }
507 | </script>
508 | ```
509 | 
510 | ### Usage
511 | 
512 | ```vue
513 | <!-- Outputs select with the id `product-form-variant-dropdown` -->
514 | <variant-dropdown
515 |   namespace="product-form"
516 |   :options="options"
517 | />
518 | 
519 | <!-- Outputs select with the id `sticky-product-form-variant-dropdown` -->
520 | <variant-dropdown
521 |   namespace="sticky-product-form"
522 |   :options="options"
523 | />
524 | ```
525 | 
526 | * Use unique data from the component's props, or add a `namespace` prop, or use a combination of both to ensure that the `id` is always unique
527 | * When using a `namespace` prop, make the prop `required` to ensure that its not missed
528 | * Utilise the browser tools and Storybook Accessibility checks that detect if an `id` is not unique
529 | * Consider your loading states as well as your standard/active states
530 |   * Often when a component is in a loading state it might not have access prop data that could be used for a unique `id` - For example using a `product.id` in an element's `id`, but the product is still being fetched and not yet set
531 |   * Consider testing your loading states to check for non-unique IDs
532 | 
533 | [ꜛ Back to TOC](#table-of-contents)
534 | 
535 | ## Additional Resources
536 | * https://www.powermapper.com/tests/screen-readers/aria/index.html
537 |   * Outlines how different ARIA attributes are handled by different screen-readers
538 | * https://webaim.org/techniques/keyboard/
539 |   * An outline of keyboard accessibility best-practices
540 |   * Also includes a table of some of the most common keyboard interactions to consider when testing a site's keyboard accessibility
541 | 
542 | [ꜛ Back to TOC](#table-of-contents)
543 | 


--------------------------------------------------------------------------------
/assets/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/we-make-websites/wmw-coding-guidelines/a0d95d7af2bd00d072c216126931b8641df97036/assets/logo.png


--------------------------------------------------------------------------------
/css/README.md:
--------------------------------------------------------------------------------
   1 | # CSS/SCSS Guidelines
   2 | 
   3 | ## Table of contents
   4 | 
   5 | * [General](#general)
   6 | * [Methods](#methods)
   7 | * [Declarations](#declarations)
   8 | * [Naming](#naming)
   9 | * [Formatting](#formatting)
  10 | * [Colours](#colours)
  11 | * [Nesting](#nesting)
  12 | * [Properties](#properties)
  13 | 
  14 | [← Back to homepage](../README.md)
  15 | 
  16 | ## General
  17 | 
  18 | * [DRY (Don't Repeat Yourself)](#dry-dont-repeat-yourself)
  19 | * [Overriding stylelint](#overriding-stylelint)
  20 | 
  21 | ### DRY (Don't Repeat Yourself)
  22 | 
  23 | #### Don't
  24 | 
  25 | ```scss
  26 | .foo {
  27 |   background-color: var(--color-neutral-3);
  28 |   border: 1px solid var(--color-neutral-1);
  29 |   color: var(--color-neutral-2);
  30 | }
  31 | 
  32 | .bar {
  33 |   background-color: var(--color-neutral-3);
  34 |   border: 1px solid var(--color-neutral-1);
  35 |   color: var(--color-neutral-2);
  36 | }
  37 | ```
  38 | 
  39 | #### Do
  40 | 
  41 | ```scss
  42 | .btn {
  43 |   background-color: var(--color-neutral-3);
  44 |   border: 1px solid var(--color-neutral-1);
  45 |   color: var(--color-neutral-2);
  46 | }
  47 | ```
  48 | 
  49 | * Keep things DRY, aim to use standard classes so you can re-use your code
  50 | * SCSS `@include` and `@extend` can encourage poor coding practice, just because it's one line in your code doesn't mean it is when compiled
  51 | * If you're applying the same include or styles on lots of selectors, create a class and apply it in HTML to keep things DRY
  52 | * Make sure you inspect elements in Figma to find their corresponding classes and CSS variables to avoid repeating them
  53 | 
  54 | #### Exceptions
  55 | 
  56 | * Sometimes it's still better to KISS (Keep It Simple, Stupid) than DRY
  57 | 
  58 | ### Overriding stylelint
  59 | 
  60 | #### Don't
  61 | 
  62 | ```scss
  63 | .foo {
  64 |   // stylelint-disable-next-line
  65 |   background-color: var(--color-neutral-1) !important;
  66 |   margin: 0;
  67 |   // stylelint-disable-next-line
  68 |   position: absolute !important;
  69 | }
  70 | 
  71 | // stylelint-disable-next-line
  72 | .barClass {
  73 |   color: var(--color-neutral-6)
  74 | }
  75 | ```
  76 | 
  77 | #### Do
  78 | 
  79 | ```scss
  80 | // stylelint-disable declaration-no-important
  81 | 
  82 | .foo {
  83 |   background-color: var(--color-neutral-1) !important;
  84 |   margin-block: 0;
  85 |   margin-inline: 0;
  86 |   position: absolute !important;
  87 | }
  88 | 
  89 | // Custom class from app
  90 | // stylelint-disable-next-line selector-class-pattern
  91 | .barClass {
  92 |   color: var(--color-neutral-6)
  93 | }
  94 | ```
  95 | 
  96 | * Sometimes it's necessary to override stylelint, usually due to app code
  97 | * When this happens do not use `stylelint-disable` to disable all linting in the whole file
  98 | * Instead use `stylelint-disable-next-line [rule]` to disable just that rule on the next line, then add a preceding comment explaining why it's necessary
  99 | * If you find yourself disabling the same rule frequently in a file then add a comment at the top of the file disabling _just_ that rule using `stylelint-disable [rule]
 100 | * Add the rule comment at the top of the file just after the intro comment with a newline between the rule comment and the first declaration block
 101 | * Add the rule comments in alphabetical order
 102 | * Stylelint will tell you which rule you're breaking when hovering over the error
 103 | * Note that the stylelint rules listed under [deprecated](https://stylelint.io/user-guide/rules/#deprecated) are supported by prefixing the rule with `stylistic/`, e.g. `stylistic/color-hex-case` instead of just `color-hex-case` as these rules are set to be removed in stylelint 16
 104 | 
 105 | [ꜛ Back to TOC](#table-of-contents)
 106 | 
 107 | ## Methods
 108 | 
 109 | * [Fullscreen elements](#fullscreen-elements)
 110 | * [Magic numbers](#magic-numbers)
 111 | * [Mobile first](#mobile-first)
 112 | * [Responsive banner padding](#responsive-banner-padding)
 113 | * [RTL](#rtl)
 114 | 
 115 | ### Fullscreen elements
 116 | 
 117 | #### Don't
 118 | 
 119 | ```scss
 120 | .foo {
 121 |   bottom: 0;
 122 |   left: 0;
 123 |   position: absolute;
 124 |   right: 0;
 125 |   top: 0;
 126 | }
 127 | ```
 128 | 
 129 | #### Do
 130 | 
 131 | ```scss
 132 | .foo {
 133 |   height: 100%;
 134 |   left: 0;
 135 |   position: absolute;
 136 |   top: 0;
 137 |   width: 100%;
 138 | }
 139 | ```
 140 | 
 141 | * Don't define all four positioning properties to set an element to fullscreen as these do not work on all elements
 142 | * Instead use `height: 100%` and `width: 100%`
 143 | 
 144 | ### Magic numbers
 145 | 
 146 | #### Don't
 147 | 
 148 | ```scss
 149 | .foo {
 150 |   left: 23px;
 151 | }
 152 | ```
 153 | 
 154 | #### Do
 155 | 
 156 | ```scss
 157 | .foo {
 158 |   // 10px because of font height
 159 |   left: calc(var(--layout-gutter) - 10px - (var(--nav-height) / 2));
 160 | }
 161 | ```
 162 | 
 163 | #### Or if you have to
 164 | ```scss
 165 | .foo {
 166 |   // This values matches the sum of widths above it
 167 |   left: 23px;
 168 | }
 169 | ```
 170 | 
 171 | * Avoid magic numbers, these are numbers that 'just work' but are set arbitrarily
 172 | * Try and use calculations to make the values relative to existing known numbers
 173 | * When someone else comes to edit they won't understand why it's this number specifically
 174 | * If you have to use magic numbers then leave a comment explaining why that number, it can be just because it works, but explain what will break if it's changed
 175 | 
 176 | > Read more about [magic numbers](https://css-tricks.com/magic-numbers-in-css/).
 177 | 
 178 | ### Mobile first
 179 | 
 180 | #### Don't
 181 | 
 182 | ```scss
 183 | .foo {
 184 |   // Desktop code
 185 | 
 186 |   @include mq($until: l) {
 187 |     // Mobile code
 188 |   }
 189 | }
 190 | ```
 191 | 
 192 | ### Do
 193 | ```scss
 194 | .foo {
 195 |   // Mobile code
 196 | 
 197 |   @include mq($from: l) {
 198 |     // Desktop code
 199 |   }
 200 | }
 201 | ```
 202 | 
 203 | * We should always develop mobile first
 204 | * This means we're expanding to fill desktop instead of cramming things in to fit mobile
 205 | * If we fail to add desktop styles then the site will still be usable
 206 | * It's still acceptable to use `$until` media queries for extensive mobile-only code which you'd only have to override in the desktop breakpoint
 207 | 
 208 | ### Responsive banner padding
 209 | 
 210 | #### Don't
 211 | 
 212 | ```scss
 213 | .foo {
 214 |   aspect-ratio: 16 / 9;
 215 |   padding-block-start: 60%;
 216 | }
 217 | ```
 218 | 
 219 | #### Do
 220 | 
 221 | ```scss
 222 | .foo {
 223 |   // 16:9 ratio
 224 |   padding-block-end: 56.25%;
 225 | }
 226 | ```
 227 | 
 228 | #### Or
 229 | 
 230 | ```scss
 231 | @use 'sass:math';
 232 | 
 233 | .foo {
 234 |   padding-block-end: percentage(math.div(9, 16));
 235 | }
 236 | ```
 237 | 
 238 | * When using padding to create a responsive banner always use `padding-block-end`
 239 | * Also add a preceding comment explaining the ratio of the banner
 240 | * We don't recommend using [`aspect-ratio`](#aspect-ratio) because in browsers that don't support it (generally relatively recent versions of Safari) it would break the layout
 241 | 
 242 | ### RTL
 243 | 
 244 | * Use properties that automatically updated based on writing direction
 245 | * See [`margin` & `padding`](#margin--padding) for details on `margin` and `padding`
 246 | * [`inset`](#inset) does not have the necessary support yet
 247 | * Continue using `top`, `right`, `bottom`, and `left` properties for now
 248 | * Use the RTL selector to switch positions in right-to-left writing directions
 249 | 
 250 | ```scss
 251 | .foo {
 252 |   left: var(--spacing-m);
 253 | 
 254 |   [dir=rtl] & {
 255 |     left: unset;
 256 |     right: var(--spacing-m);
 257 |   }
 258 | }
 259 | ```
 260 | 
 261 | [ꜛ Back to TOC](#table-of-contents)
 262 | 
 263 | ## Declarations
 264 | 
 265 | * [#IDs](#ids)
 266 | * [!important](#important)
 267 | * [Longhand properties](#longhand-properties)
 268 | * [Prefixes](#prefixes)
 269 | * [Property order](#property-order)
 270 | * [Pseudo-elements & -selectors](#pseudo-elements-&--selectors)
 271 | * [Variables](#variables)
 272 | 
 273 | ### #IDs
 274 | 
 275 | #### Don't
 276 | 
 277 | ```scss
 278 | #foo {
 279 |   background-color: var(--color-neutral-1);
 280 | }
 281 | ```
 282 | 
 283 | #### Do
 284 | 
 285 | ```scss
 286 | .foo {
 287 |   background-color: var(--color-neutral-1);
 288 | }
 289 | ```
 290 | 
 291 | * Don't use IDs, ever, definitely never use them nested under each other
 292 | * They're overly specific and trump classes when it comes to CSS specificity
 293 | 
 294 | #### Exceptions
 295 | 
 296 | * Sometimes you may have to because you're working with apps or code you can't otherwise edit
 297 | * In this case, and only as a last resort, use IDs
 298 | * Add a `// stylelint-disable selector-max-id` comment at the start of the SCSS file immediately beneath the intro comment to disable linting for it
 299 | 
 300 | ### `!important`
 301 | 
 302 | #### Don't
 303 | 
 304 | ```scss
 305 | .foo {
 306 |   color: var(--color-brand-1-default) !important;
 307 | }
 308 | ```
 309 | 
 310 | * Never use `!important` if it can be avoided
 311 | *  Add inline comments above the property explaining why if you have to use `!important`
 312 | 
 313 | #### Exceptions
 314 | 
 315 | * Sometimes you have to because of apps though
 316 | * However before using `!important` consider doubling the specificity if you're battling code that is loaded in the page after your stylesheet but not actually inline (see below)
 317 | * Add a `// stylelint-disable declaration-no-important` comment at the start of the SCSS file immediately beneath the intro comment to disable linting for it
 318 | 
 319 | #### Doubling Specificity
 320 | 
 321 | ```scss
 322 | .foo.foo {
 323 |   // This style will override .foo styles
 324 | }
 325 | ```
 326 | 
 327 | * This works because it's more specific than just the class name once, but won't override inline styles
 328 | 
 329 | > Read more about [CSS specificity](https://www.smashingmagazine.com/2007/07/css-specificity-things-you-should-know/).
 330 | 
 331 | ### Longhand properties
 332 | 
 333 | #### Don't
 334 | 
 335 | ```scss
 336 | .foo {
 337 |   background: url('/path/to/image.jpg') no-repeat 50% 50% var(--color-neutral-6);
 338 |   font: var(--font-size-m)/var(--line-height-0) var(--font-family-1);
 339 | }
 340 | ```
 341 | 
 342 | #### Do
 343 | 
 344 | ```scss
 345 | .foo {
 346 |   background-color: var(--color-neutral-6);
 347 |   background-image: url('/path/to/image.jpg');
 348 |   background-position: 50% 50%;
 349 |   background-repeat: no-repeat;
 350 |   font-family: var(--font-family-1);
 351 |   font-size: var(--font-size-m);
 352 |   line-height: var(--line-height-0);
 353 | }
 354 | ```
 355 | 
 356 | * Avoid the shorthand `background` and `font` properties
 357 | * For these properties the non-described properties automatically are set to `none`/`default`/`0` which causes issues
 358 | * It's also recommended that you don't use [`transform`](#transform)
 359 | 
 360 | #### Exceptions
 361 | 
 362 | * You can use `margin` or `padding` if all the values are the same, or if you're setting the same value for both vertical properties, and both horizontal properties
 363 | * Feel free to use shorthand properties for `border` and `transform`
 364 | 
 365 | ```scss
 366 | .foo {
 367 |   // This is okay
 368 |   margin: var(--spacing-m) var(--spacing-l);
 369 |   // This isn't okay as left and right have different values
 370 |   margin: var(--spacing-m) var(--spacing-l) var(--spacing-m) var(--spacing-xl);
 371 |   // Instead of the above use the following, can't use margin-block as Safari doesn't support it fully
 372 |   margin-block-end: var(--spacing-m);
 373 |   margin-block-start: var(--spacing-m);
 374 |   margin-inline-end: var(--spacing-l);
 375 |   margin-inline-start: var(--spacing-xl);
 376 | }
 377 | ```
 378 | 
 379 | ### Prefixes
 380 | 
 381 | * Prefixes are automatically added to to CSS properties
 382 | * This also means that unused prefixes are automatically removed, if you definitely need the prefix then use the following:
 383 | 
 384 | ```scss
 385 | /* autoprefixer: ignore next */
 386 | -webkit-prefixed-property: value;
 387 | ```
 388 | 
 389 | ### Property order
 390 | 
 391 | ```scss
 392 | .foo {
 393 |   // Includes
 394 |   @include transition(opacity);
 395 |   // Extends
 396 |   @extend .grid;
 397 |   // CSS variables
 398 |   --variable: var(--spacing-m);
 399 |   // SASS variables
 400 |   $parent: &;
 401 |   // Properties in alphabetical order
 402 |   background-color: transparent;
 403 |   border: 0;
 404 |   display: flex;
 405 |   // Prefixed properties should be in alphabetical order based on the property
 406 |   // itself, ignoring the prefix
 407 |   -webkit-line-clamp: unset;
 408 |   z-index: var(--layer-raised);
 409 | 
 410 |   // Pseudo-elements
 411 |   &::before,
 412 |   &::after {
 413 |     content: '';
 414 |   }
 415 | 
 416 |   // Nested elements
 417 |   &__bar {
 418 |     color: var(--color-neutral-4);
 419 |   }
 420 | 
 421 |   // Direct descendents
 422 |   > .baz {
 423 |     color: var(--color-neutral-3);
 424 |   }
 425 | 
 426 |   // Sibling selectors
 427 |   + .bam,
 428 |   ~ .bam {
 429 |     padding-inline-start: 0;
 430 |   }
 431 | 
 432 |   // Pseudo-selectors
 433 |   &:hover,
 434 |   &:focus {
 435 |     border: 1px solid var(--color-brand-1-default)
 436 |   }
 437 | 
 438 |   // Modifiers
 439 |   &#{&}--big {
 440 |     width: 100%;
 441 | 
 442 |     // Use $parent SASS variable to avoid re-writing parent selector
 443 |     #{$parent}__bar {
 444 |       color: var(--color-neutral-1);
 445 |     }
 446 |   }
 447 | 
 448 |   // Parent selectors
 449 |   .parent & {
 450 |     display: none;
 451 |   }
 452 | 
 453 |   // @media queries
 454 |   @media print {}
 455 | 
 456 |   // @supports queries
 457 |   @supports (grid-template-columns: subgrid) {}
 458 | 
 459 |   // mq media queries
 460 |   @include mq($from: l) {}
 461 | }
 462 | ```
 463 | 
 464 | The order should be as follows, all items within each group should be sorted alphabetically:
 465 | 1. Includes (e.g. `@include transition(opacity)`)
 466 | 1. Extends (e.g. `@extend .grid`)
 467 | 1. CSS variables (e.g. `--variable`)
 468 | 1. SASS variables (e.g. `$parent`)
 469 | 1. Properties (e.g. `background-color`)
 470 | 1. Pseudo-elements (e.g. `&::before`, `&::after`, `&::placeholder` etc.)
 471 | 1. Nested elements (e.g. `&__bar`)
 472 | 1. Direct descendants (e.g. `> .baz`)
 473 | 1. Sibling selectors (e.g. `+ .bam`, `~ .bam`, etc.)
 474 | 1. Pseudo-selectors (e.g. `&:hover`, `&:focus`, etc.), this way they can change nested elements
 475 | 1. Modifiers (e.g. `&#{&}--big`), this gives them precedence over all nested elements
 476 | 1. Parent selectors (e.g. `.parent &`), so that they have the greatest priority
 477 | 1. Media queries (e.g. `@media print`)
 478 | 1. Support queries (e.g. `@supports (grid-template-columns: subgrid)`)
 479 | 1. MQ media queries (e.g. `@include mq($from: l)`)
 480 | 
 481 | ### Pseudo-elements & -selectors
 482 | 
 483 | #### Don't
 484 | 
 485 | ```scss
 486 | .foo {
 487 |   &:after {}
 488 | 
 489 |   &:placeholder {}
 490 | }
 491 | ```
 492 | 
 493 | #### Do
 494 | 
 495 | ```scss
 496 | .foo {
 497 |   &::after {}
 498 | 
 499 |   &::placeholder {}
 500 | 
 501 |   &:hover {}
 502 | }
 503 | ```
 504 | 
 505 | * Pseudo-elements should use `::` (after, before, first-letter, first-line, marker, placeholder, and selection)
 506 | * Pseudo-selectors should use `:` (hover, focus, active, nth-child etc.)
 507 | * This helps differentiate between an element and a selector
 508 | 
 509 | ### Variables
 510 | 
 511 | **If you're using Canvas 3.0.0 or newer then use the `design` command in conjunction with the _tokens.json_ file that the designer provided to automatically create your project's variable and classes. [See documentation](https://we-make-websites.gitbook.io/canvas/features/styles/design-tokens)**
 512 | 
 513 | When first setting up your project you should go through and define a series of variables and mixins to help with the maintenance of the project, it's a lot easier to change the property of one variable rather than hunting for all appearances of, say, a `font-family`.
 514 | 
 515 | It is the project lead developer's responsibility to set them up to maintain conformity.
 516 | 
 517 | [ꜛ Back to TOC](#table-of-contents)
 518 | 
 519 | ## Naming
 520 | 
 521 | * [BEM & CSS](#bem-&-css)
 522 | * [BEM modifiers](#bem-modifiers)
 523 | * [BEM naming](#bem-naming)
 524 | * [Descriptive naming](#descriptive-naming)
 525 | * [Naming conventions](#naming-conventions)
 526 | * [Variable naming](#variable-naming)
 527 | * [Naming conventions](#naming-conventions)
 528 | 
 529 | ### BEM & CSS
 530 | 
 531 | #### About
 532 | 
 533 | **BEM** stands for Block Element Modifier and is a element class naming convention intended to standardise the way elements are named so everyone is on the same page and can work out the relationship of elements without having to refer back to the HTML constantly.
 534 | 
 535 | > For more information go to [Get BEM](http://getbem.com/).
 536 | 
 537 | Below is an ideal example of how BEM would be used across HTML and CSS (technically SCSS).
 538 | 
 539 | #### HTML
 540 | This HTML example also includes a suggested way of targeting elements in JavaScript (`js-click`).
 541 | 
 542 | ```html
 543 | <div class="product">
 544 |   <h1 class="product__title"></h1>
 545 |   <h2 class="product__subtitle"></h2>
 546 | 
 547 |   <div class="product__image-container">
 548 |     <img src="" class="product__image" alt="" js-click="zoom-image">
 549 |     <!-- Suggest adding srcset and sizes for responsive images -->
 550 |   </div>
 551 | 
 552 |   <div class="product__description">
 553 |     <ul class="product-icons">
 554 |       <li class="product-icons__icon"><li>
 555 |       <li class="product-icons__icon"><li>
 556 |       <li class="product-icons__icon product-icons__icon--large"><li>
 557 |     </ul>
 558 |     <!-- Note how this is its own content block as .product__description__product-icons isn't valid BEM -->
 559 |     <!-- If you find yourself thinking you need to nest blocks within blocks then instead make a new container -->
 560 |     <!-- Also note that when using modifying classes you must still include the base non-modified classes -->
 561 |   </div>
 562 | </div>
 563 | ```
 564 | 
 565 | ```html
 566 | <div class="product-card">
 567 |   <ul class="product-icons">
 568 |     <li class="product-icons__icon"><li>
 569 |     <li class="product-icons__icon"><li>
 570 |     <li class="product-icons__icon product-icons__icon--large"><li>
 571 |   </ul>
 572 | </div>
 573 | ```
 574 | 
 575 | #### CSS
 576 | 
 577 | ```scss
 578 | // product.scss
 579 | .product {
 580 |   &__title {}
 581 | 
 582 |   &__subtitle {}
 583 | 
 584 |   &__image-container {}
 585 | 
 586 |   &__image {}
 587 | 
 588 |   &__description {}
 589 | 
 590 |   // Newlines and spacing removed for brevity
 591 |   // Even without comments we can see what we're editing
 592 |   // It doesn't matter if subtitle becomes another element for example
 593 | }
 594 | ```
 595 | ```scss
 596 | // product-icons.scss
 597 | .product-icons {
 598 |   &__icon {
 599 |     &#{&}--large {
 600 |       // We're already at three levels deep so always keep an eye on your nesting
 601 |     }
 602 |   }
 603 | 
 604 |   .product-card & {
 605 |     // Keep all the code for .product-icons in one place by qualifying its context
 606 |     // Code here will only apply to .product-icons when inside .product-card
 607 |   }
 608 | }
 609 | ```
 610 | 
 611 | ### BEM modifiers
 612 | 
 613 | #### Don't
 614 | 
 615 | ```html
 616 | <div class="bad"></div>
 617 | <div class="bad--modifier"></div>
 618 | ```
 619 | ```scss
 620 | .bad {
 621 |   &--modifier {}
 622 | }
 623 | ```
 624 | 
 625 | #### Do
 626 | 
 627 | ```html
 628 | <div class="good good--modifier"></div>
 629 | ```
 630 | ```scss
 631 | .good {
 632 |   &#{&}--modifier {}
 633 | }
 634 | ```
 635 | 
 636 | * Don't just apply the modifier class and extend the block/element class
 637 | * Apply the block/element as a class as well as the modifier class
 638 | * Using interpolated brackets means the CSS will compile as `.good.good--modifier {}`
 639 | 
 640 | ### Concatenating
 641 | 
 642 | #### Don't
 643 | 
 644 | ```scss
 645 | .foo {
 646 |   .foo__bar {
 647 |     &-bez {}
 648 |     .foo__bar--modifier {}
 649 |   }
 650 | }
 651 | ```
 652 | 
 653 | #### Do
 654 | 
 655 | ```scss
 656 | .foo {
 657 |   &__bar {
 658 |     &#{&}--modifier {}
 659 |   }
 660 | 
 661 |   &__bar-bez {}
 662 | }
 663 | ```
 664 | 
 665 | * Keeps the BEM naming and nesting of selectors more obvious
 666 | * The modifier has interpolation brackets `#{}` because `&&` is invalid SCSS
 667 | * The modifier will compile as `.foo__bar.foo__bar--modifier` in CSS
 668 | * This means it has greater specificity, without this any later changes to `.foo__bar` would override the modifier (for example in media queries) as `.foo__bar` and `.foo__bar--modifier` would have the same specificity so the properties applied later in the file would trump the modifier's
 669 | 
 670 | #### Don't
 671 | 
 672 | ```scss
 673 | .foo {
 674 |   &__bar {
 675 |     &-bez {}
 676 |   }
 677 | }
 678 | ```
 679 | 
 680 | #### Do
 681 | 
 682 | ```scss
 683 | .foo {
 684 |   &__bar {}
 685 |   &__bar-bez {}
 686 | }
 687 | ```
 688 | 
 689 | * Do not use concatenation to join hyphenated class names
 690 | 
 691 | > Read more about [CSS specificity](https://www.smashingmagazine.com/2007/07/css-specificity-things-you-should-know/).
 692 | 
 693 | ### BEM naming
 694 | 
 695 | #### Don't
 696 | 
 697 | ```scss
 698 | .site-search {}
 699 | .site-search label {}
 700 | .site-search input {}
 701 | ```
 702 | 
 703 | #### Do
 704 | 
 705 | ```scss
 706 | .site-search {}
 707 | .site-search__title {}
 708 | .site-search__field {}
 709 | ```
 710 | 
 711 | * Always use classes to select elements
 712 | * Elements may change and no longer be a `<label>` or `<input>`, breaking the CSS, causing maintenance issues
 713 | * With decent BEM naming you shouldn't need to comment your CSS to say what things are or where they sit
 714 | * Class names should be kebab-case
 715 | 
 716 | #### Exceptions
 717 | 
 718 | * Feel free to write comments to explain why you've done things strangely if you have had to
 719 | 
 720 | ### Descriptive naming
 721 | 
 722 | #### Don't
 723 | 
 724 | ```scss
 725 | .curley-font {
 726 |   font-family: 'Lobster', serif;
 727 | }
 728 | 
 729 | .red {
 730 |   color: var(--color-red);
 731 | }
 732 | ```
 733 | 
 734 | #### Do
 735 | 
 736 | ```scss
 737 | .blog__subtitle {
 738 |   font-family: 'Lobster', serif;
 739 | }
 740 | 
 741 | .text-highlight {
 742 |   color: var(--color-red);
 743 | }
 744 | ```
 745 | 
 746 | * CSS selectors should describe hierarchy, not the look as the look can change
 747 | 
 748 | ### Naming conventions
 749 | 
 750 | #### Don't
 751 | 
 752 | ```scss
 753 | @function FunctionName() {}
 754 | 
 755 | @mixin mixin_name() {}
 756 | 
 757 | @keyframes KEYFRAME_NAME() {}
 758 | ```
 759 | 
 760 | #### Do
 761 | 
 762 | ```scss
 763 | @function function-name() {}
 764 | 
 765 | @mixin mixin-name() {}
 766 | 
 767 | @keyframes keyframe-name() {}
 768 | ```
 769 | 
 770 | * Functions, mixins, and keyframes should all be kebab-case
 771 | 
 772 | ### Variable naming
 773 | 
 774 | #### Canvas 3.0.0 and newer
 775 | * Use the `design` command
 776 | * Use kebab-case for CSS and SCSS variables
 777 | * Global CSS variables should be set in the `:root {}` declaration
 778 | * Global SCSS variables should be set in a SCSS file in the _styles/config/_ folder
 779 | * Local CSS and SCSS variables are only available in the declaration they are defined in
 780 | * Prefer CSS variables, only use SCSS variables where SCSS functions would break with CSS variables
 781 | 
 782 | #### Before Canvas 3.0.0
 783 | 
 784 | * For global variables use `$SCREAMING_SNAKE_CASE`
 785 | * For local variables use `$snake_case`
 786 | * Local variables are only available in the declaration they are defined in
 787 | 
 788 | ### Naming conventions
 789 | 
 790 | #### Don't
 791 | 
 792 | ```scss
 793 | @function FunctionName() {}
 794 | 
 795 | @mixin mixin_name() {}
 796 | 
 797 | @keyframes KEYFRAME_NAME() {}
 798 | ```
 799 | 
 800 | #### Do
 801 | 
 802 | ```scss
 803 | @function function-name() {}
 804 | 
 805 | @mixin mixin-name() {}
 806 | 
 807 | @keyframes keyframe-name() {}
 808 | ```
 809 | 
 810 | * Functions, mixins, and keyframes should all be kebab-case
 811 | 
 812 | [ꜛ Back to TOC](#table-of-contents)
 813 | 
 814 | ## Formatting
 815 | 
 816 | * [Calculations](#calculation)
 817 | * [Capitalisation](#capitalisation)
 818 | * [Commenting (inline)](#commenting-inline)
 819 | * [Commenting (loud)](#commenting-loud)
 820 | * [Commenting (introductory)](#commenting-introductory)
 821 | * [Indenting](#indenting)
 822 | * [Negative CSS variables](#negative-css-variables)
 823 | * [Parenthesise on @includes](#parenthesise-on-includes)
 824 | * [Whitespace](#whitespace)
 825 | * [Zero values & units](#zero-values--units)
 826 | 
 827 | ### Calculations
 828 | 
 829 | #### Don't
 830 | 
 831 | ```scss
 832 | .foo {
 833 |   left: calc(100% - 30px * 2);
 834 |   width: 100% / 3;
 835 | }
 836 | ```
 837 | 
 838 | #### Do
 839 | 
 840 | ```scss
 841 | .foo {
 842 |   left: calc(100% - (var(--gutter) * 2));
 843 |   width: (100% / 3);
 844 | }
 845 | ```
 846 | 
 847 | * Wrap calculations in brackets for readability
 848 | * Put spaces between the values and the mathematical operators
 849 | * Put multiplying and dividing values after the starting value
 850 | * Use variables in calculations to keep them relative
 851 | 
 852 | #### Also
 853 | ```scss
 854 | .foo {
 855 |   --local-margin: (2 * var(--global-margin));
 856 |   margin-block-end: var(--local-margin);
 857 |   width: calc(100% + var(--local-margin));
 858 | }
 859 | ```
 860 | 
 861 | * Use local variables to define adjusted global variables
 862 | 
 863 | ### Capitalisation
 864 | 
 865 | #### Don't
 866 | 
 867 | ```scss
 868 | .Foo {
 869 |   Color: var(--Color-Neutral-2);
 870 | }
 871 | ```
 872 | 
 873 | #### Do
 874 | 
 875 | ```scss
 876 | .foo {
 877 |   color: var(--color-neutral-2);
 878 | }
 879 | ```
 880 | 
 881 | * Use kebab-case for selectors and properties
 882 | * Refer to [Variable naming](#variable-naming) for global and local variables
 883 | 
 884 | ### Commenting (inline)
 885 | 
 886 | #### Don't
 887 | 
 888 | ```scss
 889 | .foo {
 890 |   background-color: red; // Don't
 891 |   /* padding-block-start: 30px;
 892 |   width: 100% */
 893 | }
 894 | ```
 895 | 
 896 | #### Do
 897 | 
 898 | ```scss
 899 | .foo {
 900 |   // Comment above the line
 901 |   background-color: red;
 902 |   // padding-block-start: 30px;
 903 |   // width: 100%;
 904 | }
 905 | ```
 906 | 
 907 | * Use `//` for inline comments not the block level `/* */`
 908 | * It's easier to un-comment
 909 | * Inline comments should start on a new line preceding the property they're describing
 910 | * Use sentence case for your comments
 911 | * Do not end with a full stop
 912 | 
 913 | ### Commenting (loud)
 914 | 
 915 | ```scss
 916 | .foo {
 917 |   color: var(--color-neutral-2);
 918 |   width: 100%;
 919 | 
 920 |   /**
 921 |    * Media queries.
 922 |    */
 923 |   @include mq($from: l) {
 924 |     color: var(--color-neutral-1);
 925 |   }
 926 | }
 927 | ```
 928 | 
 929 | * Loud comments can be used to break up long code and make it easier to navigate
 930 | * Use the format above for loud comments
 931 | * Use sentence case for your comments
 932 | * End each line with a full stop
 933 | 
 934 | ### Commenting (introductory)
 935 | 
 936 | ```css
 937 | /**
 938 |  * Component: Footer Social
 939 |  * -----------------------------------------------------------------------------
 940 |  * Social icons and links in footer.
 941 |  *
 942 |  */
 943 | ```
 944 | 
 945 | * Include an introductory comment at the start of each file
 946 | * Describe what folder it's in, the file's name, and list any special features or conditions
 947 | * All lines except the first one should have a full stop
 948 | 
 949 | ### Indenting
 950 | 
 951 | #### Don't
 952 | 
 953 | ```scss
 954 | .foo {
 955 |     color: red;
 956 | 
 957 |     &_bar {
 958 |         // No good
 959 |     }
 960 | }
 961 | ```
 962 | 
 963 | #### Do
 964 | 
 965 | ```scss
 966 | .foo {
 967 |   color: red;
 968 | 
 969 |   &_bar {
 970 |     // Better
 971 |   }
 972 | }
 973 | ```
 974 | 
 975 | * Indent with 2 spaces, not tabs or 4 spaces
 976 | * Shopify uses 2 spaces
 977 | * Using spaces is easier to copy and paste
 978 | 
 979 | ### Negative CSS variables
 980 | 
 981 | #### Don't
 982 | 
 983 | ```scss
 984 | $margin: var(--spacing-m);
 985 | 
 986 | .foo {
 987 |   margin-block-start: -$margin;
 988 | }
 989 | ```
 990 | 
 991 | #### Do
 992 | 
 993 | ```scss
 994 | .foo {
 995 |   margin-block-start: calc(var(--spacing-m) * -1);
 996 | }
 997 | ```
 998 | 
 999 | * To use negative values for CSS variables you have to times them by `-1` in a `calc()` function
1000 | 
1001 | ### Parenthesise on @includes
1002 | 
1003 | #### Where
1004 | 
1005 | ```scss
1006 | @mixin animation($property: color) {
1007 |   // Code
1008 | }
1009 | 
1010 | @mixin visually-hidden() {
1011 |   // Code
1012 | }
1013 | ```
1014 | 
1015 | #### Don't
1016 | 
1017 | ```scss
1018 | .foo {
1019 |   @include visually-hidden();
1020 | }
1021 | ```
1022 | 
1023 | #### Do
1024 | 
1025 | ```scss
1026 | .foo {
1027 |   @include animation(background-color);
1028 |   @include visually-hidden;
1029 | }
1030 | ```
1031 | 
1032 | * Do not include parenthesise on argument-less mixins
1033 | 
1034 | ### Whitespace
1035 | 
1036 | #### Don't
1037 | 
1038 | ```scss
1039 | .foo{box-shadow: 0 0 rgba(0,0,0,0.5);color:red;font:{size:1em;weight:700;}}
1040 | 
1041 | .foo,.spanner,.foobar{
1042 |   color:red;
1043 |   .baz{color:blue}}
1044 | 
1045 | .foo>.bar {color:red;}
1046 | ```
1047 | 
1048 | #### Do
1049 | 
1050 | ```scss
1051 | .foo {
1052 |   box-shadow: 0 0 rgba(0, 0, 0, 0.5);
1053 |   color: rgb(255, 0, 0);
1054 |   font-size: 1rem;
1055 |   font-weight: 700;
1056 | }
1057 | 
1058 | .foo, .foobar,
1059 | .spanner {
1060 |   color: rgb(0, 255, 0);
1061 | 
1062 |   .baz {
1063 |     color: rgb(0, 0, 255);
1064 |   }
1065 | }
1066 | 
1067 | .foo > .bar {
1068 |   color: rgb(255, 0, 0);
1069 | }
1070 | ```
1071 | 
1072 | * Add whitespace after commas (including property values), after selector name, after property colon and before and after child selector
1073 | * Each element selector block should have an empty line above it
1074 | * Each property on a new line and a new line for the closing }
1075 | * Keep related selectors on the same line, separate selectors go on a new line
1076 | * Add spaces between child selectors
1077 | * Put a semi-colon after a property, even if it's the last one
1078 | * Put a newline after the last selector
1079 | 
1080 | #### Why
1081 | * It's easier to read
1082 | * Whitespace is free
1083 | * Code is minified anyway
1084 | 
1085 | ### Zero values & units
1086 | 
1087 | #### Don't
1088 | 
1089 | ```scss
1090 | .foo {
1091 |   animation-delay: 0;
1092 |   margin-block: 0px;
1093 |   opacity: .4567;
1094 | }
1095 | ```
1096 | 
1097 | #### Do
1098 | ```scss
1099 | .foo {
1100 |   animation-delay: 0s;
1101 |   margin-block: 0;
1102 |   opacity: 0.4;
1103 | }
1104 | ```
1105 | 
1106 | * Do specify units on zero duration times
1107 | * Don't specify units on zero length values
1108 | * Do add a leading zero for decimal places
1109 | * Don't go to more than three decimal places, the fewer the better
1110 | 
1111 | [ꜛ Back to TOC](#table-of-contents)
1112 | 
1113 | ## Colours
1114 | 
1115 | * [Colour properties](#colour-properties)
1116 | * [Colour variables](#colour-variables)
1117 | 
1118 | ### Colour properties
1119 | 
1120 | #### Don't
1121 | 
1122 | ```scss
1123 | .foo {
1124 |   color: red;
1125 |   // Or
1126 |   color: #FF0000;
1127 |   // Or
1128 |   color: hsl(0, 100%, 50%);
1129 | }
1130 | ```
1131 | 
1132 | #### Do
1133 | 
1134 | ```scss
1135 | .foo {
1136 |   color: rgb(255 0 0);
1137 |   // Or
1138 |   color: rgb(255 0 0 / 50%);
1139 | }
1140 | ```
1141 | 
1142 | * Use `rgb()` colour functions using space separation as they are more human readable
1143 | * Do not use comma separated `rgb()` colour functions
1144 | * These values are often supplied in brand guidelines
1145 | 
1146 | #### Exceptions
1147 | 
1148 | * If required, use lowercase and shorthand (where possible) hex colour values
1149 | 
1150 | ### Colour variables
1151 | 
1152 | #### Don't
1153 | 
1154 | ```scss
1155 | $colour-blue-other: #6195ed;
1156 | $colour-dark-grey: #E2E3E4;
1157 | $LIGHT_GREY: #d4d7d9;
1158 | ```
1159 | 
1160 | #### Do
1161 | 
1162 | ```scss
1163 | --color-brand-1-default: rgb(97 149 237);
1164 | --color-neutral-2: rgb(226 227 228);
1165 | --color-neutral-3: rgb(212 215 217);
1166 | ```
1167 | 
1168 | * Use the `design` command to generate variables and classes
1169 | * All colours should have variables defined for them, this will come from the designs
1170 | * Designers will determine the name of colours
1171 | 
1172 | [ꜛ Back to TOC](#table-of-contents)
1173 | 
1174 | ## Nesting
1175 | 
1176 | * [Nesting levels](#nesting-levels)
1177 | * [Nesting media queries](#nesting-media-queries)
1178 | 
1179 | ### Nesting levels
1180 | 
1181 | #### Don't
1182 | 
1183 | ```scss
1184 | .foo {
1185 |   .this {
1186 |     .is {
1187 |       .very {
1188 |         .bad {
1189 | 
1190 |         }
1191 |       }
1192 |     }
1193 |   }
1194 | 
1195 |   @include mq($from: l) {
1196 |     .this .is .very .bad {
1197 | 
1198 |     }
1199 |   }
1200 | }
1201 | ```
1202 | 
1203 | #### Do
1204 | 
1205 | ```scss
1206 | .foo {
1207 |   // Base level (not included)
1208 | 
1209 |   &__bar {
1210 |     // Level one
1211 | 
1212 |     &:hover {
1213 |       // Level two
1214 | 
1215 |       &.bar {
1216 |         // Level three
1217 |       }
1218 |     }
1219 |   }
1220 | 
1221 |   @include mq($from: l) {
1222 |     // Base level (not included)
1223 | 
1224 |     &__bar {
1225 |       // Level one
1226 | 
1227 |       &:hover {
1228 |         // Level two
1229 | 
1230 |         &.bar {
1231 |           // Level three
1232 |         }
1233 |       }
1234 |     }
1235 |   }
1236 | }
1237 | ```
1238 | 
1239 | * Don't nest more than 3 levels
1240 | * As styles would require an even more specific selector to override them
1241 | * This would quickly add up to a significant maintenance issue
1242 | * This does mean that you can't always nest properties the way you normally would
1243 | * Media queries are not included when counting levels of nesting
1244 | * VS Code can show you how many levels deep you are in its Breadcrumbs feature (View > Toggle Breadcrumbs)
1245 | 
1246 | ### Nesting media queries
1247 | 
1248 | #### Don't
1249 | 
1250 | ```scss
1251 | .foo {
1252 | 
1253 |   &__bar {
1254 |     // Code
1255 | 
1256 |     @include mq($from: m) {
1257 |       // Code
1258 |     }
1259 |   }
1260 | 
1261 |   &__section {
1262 |     // Code
1263 | 
1264 |     @include mq($from: m) {
1265 |       // Code
1266 |     }
1267 |   }
1268 | }
1269 | ```
1270 | 
1271 | #### Do
1272 | 
1273 | ```scss
1274 | .foo {
1275 | 
1276 |   &__bar {
1277 |     // Code
1278 |   }
1279 | 
1280 |   &__section {
1281 |     // Code
1282 |   }
1283 | 
1284 |   /**
1285 |    * Media queries.
1286 |    */
1287 |   @include mq($from: m) {
1288 |     &__bar {
1289 |       // Code
1290 |     }
1291 | 
1292 |     &__section {
1293 |       // Code
1294 |     }
1295 |   }
1296 | }
1297 | ```
1298 | 
1299 | * Keep media queries at the root of the declaration, not nested inside each selector
1300 | * This way it's easier to find media queries
1301 | 
1302 | [ꜛ Back to TOC](#table-of-contents)
1303 | 
1304 | ## Properties
1305 | 
1306 | * [`aspect-ratio`](#aspect-ratio)
1307 | * [`border`](#border)
1308 | * [`font-family`](#font-family)
1309 | * [`font-size`](#font-size)
1310 | * [`height` & `width`](#height--width)
1311 | * [`inset`](#inset)
1312 | * [`line-height`](#line-height)
1313 | * [`margin` & `padding`](#margin--padding)
1314 | * [`transform`](#transform)
1315 | * [`transition`](#transition)
1316 | 
1317 | ### `aspect-ratio`
1318 | 
1319 | * We don't recommend using `aspect-ratio` because in browsers that don't support it (generally relatively recent versions of Safari) it would break the layout
1320 | * See [responsive banner padding](#responsive-banner-padding) for an alternative
1321 | 
1322 | ### `border`
1323 | 
1324 | #### Don't
1325 | 
1326 | ```scss
1327 | .foo {
1328 |   border: none;
1329 | }
1330 | 
1331 | .bar {
1332 |   border: 2px solid var(--color-neutral-5);
1333 | 
1334 |   &:hover {
1335 |     border: 2px solid var(--color-neutral-1);
1336 |   }
1337 | }
1338 | ```
1339 | 
1340 | #### Do
1341 | 
1342 | ```scss
1343 | .foo {
1344 |   border: 0;
1345 | }
1346 | 
1347 | .bar {
1348 |   border: 2px solid var(--color-neutral-5);
1349 | 
1350 |   &:hover {
1351 |     border-color: var(--color-neutral-1);
1352 |   }
1353 | }
1354 | ```
1355 | 
1356 | * Use `0` instead of `none` for borders
1357 | * When a border is set to `0` it will never display, however if a border is set to `none` but later overridden by a `border-style` it will display
1358 | * If you're changing a single part of the property then target that specific property rather than setting all the properties again, this is much easier to maintain
1359 | 
1360 | ### `font-family`
1361 | 
1362 | #### Don't
1363 | 
1364 | ```scss
1365 | .foo {
1366 |   font-family: 'Avenir';
1367 | }
1368 | ```
1369 | 
1370 | #### Do
1371 | 
1372 | ```scss
1373 | :root {
1374 |   --font-family-1: 'Avenir', Helvetica, Arial, sans-serif;
1375 | }
1376 | 
1377 | .foo {
1378 |   font-family: var(--font-family-1);
1379 | }
1380 | ```
1381 | 
1382 | * Don't just declare the custom font
1383 | * Always provide a font stack which includes web-safe fonts
1384 | * Edit `fontStacks` in _design.config.js_ in Canvas to add font stacks
1385 | * This prevents loading blank pages until the font loads
1386 | * The `font-family` should be declared in a global variable
1387 | 
1388 | ### `height` & `width`
1389 | 
1390 | #### Don't
1391 | 
1392 | ```scss
1393 | .foo {
1394 |   height: calc(var(--spacing-m) + var(--spacing-2xs));
1395 |   width: 32px;
1396 | }
1397 | ```
1398 | 
1399 | #### Do
1400 | 
1401 | ```scss
1402 | .foo {
1403 |   height: 1.25rem;
1404 |   width: 2rem;
1405 | }
1406 | ```
1407 | 
1408 | * Don't use spacing variables to build `height` or `width` values
1409 | * Don't use `px` units for `height` or `width` values
1410 | * Instead use `rem` values
1411 | * The spacing variables are only intended to keep spacing relative and not for dimensions
1412 | * `rem` units scale relatively when the user zooms in, whereas `px` units may cause issues
1413 | 
1414 | #### Exceptions
1415 | 
1416 | ```scss
1417 | .icon {
1418 |   height: var(--icon-m);
1419 |   width: var(--icon-m);
1420 | }
1421 | ```
1422 | 
1423 | * There are existing variables for icon sizes
1424 | * Use these for icon element styles
1425 | 
1426 | ### `font-size`
1427 | 
1428 | #### Don't
1429 | 
1430 | ```scss
1431 | .foo {
1432 |   font-size: 12px;
1433 |   // Or
1434 |   font-size: 1em;
1435 | }
1436 | ```
1437 | 
1438 | #### Do
1439 | 
1440 | ```scss
1441 | :root {
1442 |   --font-size-m: 1rem;
1443 | }
1444 | 
1445 | .foo {
1446 |   // Canvas 3.0.0 or newer
1447 |   font-size: var(--font-size-m);
1448 |   // Before Canvas 3.0.0
1449 |   @include ms(0);
1450 | }
1451 | ```
1452 | 
1453 | * Use rem, relative ems
1454 | * They're easier to understand as they're always relative to the base font-size
1455 | * `em` units change based on the current elements `font-size`
1456 | * `px` units are not as responsive to device or zoom level
1457 | * Canvas 3.0.0 or newer defines font sizes as global variables
1458 | * Before Canvas 3.0.0 we used the font function `ms()`
1459 | 
1460 | ### `inset`
1461 | 
1462 | * The `inset` property (and its longhand versions) do not have full browser support yet, avoid using
1463 | * See [RTL](#rtl) for more details
1464 | 
1465 | ### `line-height`
1466 | 
1467 | #### Don't
1468 | 
1469 | ```scss
1470 | .foo {
1471 |   line-height: 18.5px;
1472 | }
1473 | 
1474 | .bar {
1475 |   line-height: 2.35rem;
1476 | }
1477 | ```
1478 | 
1479 | #### Do
1480 | 
1481 | ```scss
1482 | .foo {
1483 |   line-height: 160%;
1484 | }
1485 | ```
1486 | 
1487 | * Use `%` units for relative `line-height`
1488 | * This means `line-height` will scale with the font size rather than being fixed
1489 | * Another consideration at the design phase is to keep `line-height` relative to the `font-size` in rational numbers
1490 | 
1491 | ### `margin` & `padding`
1492 | 
1493 | #### Don't
1494 | 
1495 | ```scss
1496 | .foo {
1497 |   margin-top: var(--spacing-xs);
1498 |   margin-right: calc(var(--spacing-s) - var(--spacing-3xs));
1499 |   padding-bottom: var(--spacing-m);
1500 |   padding-left: var(--spacing-l);
1501 | }
1502 | ```
1503 | 
1504 | #### Do
1505 | 
1506 | ```scss
1507 | .foo {
1508 |   margin-block-start: var(--spacing-xs);
1509 |   margin-inline-end: var(--spacing-s);
1510 |   padding-block-end: var(--spacing-m);
1511 |   padding-inline-start: var(--spacing-l);
1512 | }
1513 | ```
1514 | 
1515 | #### Logical properties
1516 | * Use `margin-block-*`, `margin-inline-*`, `padding-block-*`, and `padding-inline-*` properties
1517 | * These reflect the current `writing-mode`, `direction`, and `text-orientation` of the page meaning they better support multi-language, especially right-to-left languages
1518 | * Be wary of using `margin-block-start` as vertical margins collapse
1519 | * Use `margin` and `padding` shorthand properties only when all values match, or if values of properties on the same axis match
1520 | * Safari does not support CSS variables when using `margin-block`, `margin-inline`, `padding-block`, and `padding-inline` so use individual styles when using CSS variables
1521 | 
1522 | > Read more about [`margin-block`](https://developer.mozilla.org/en-US/docs/Web/CSS/margin-block), [`margin-inline`](https://developer.mozilla.org/en-US/docs/Web/CSS/margin-inline), [`padding-block`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block), and [`padding-inline`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline).
1523 | 
1524 | #### Variable calculations
1525 | * Don't use `calc()` to combine spacing variables to perfectly match the pixel value of designs
1526 | * Instead use the closest existing spacing variable if possible
1527 | * Where the difference between the desired value and the available variables is too great you can use `calc()`, just remember to add a [magic number comment](#magic-numbers) explaining why
1528 | 
1529 | ### `transform`
1530 | 
1531 | #### Don't
1532 | 
1533 | ```scss
1534 | .foo {
1535 |   transform: translateY(var(--spacing-m)) scale(2) rotate(45deg)
1536 | }
1537 | ```
1538 | 
1539 | #### Do
1540 | 
1541 | ```scss
1542 | .foo {
1543 |   rotate: 45deg;
1544 |   scale: 2;
1545 |   translate: 0 var(--spacing-m);
1546 | }
1547 | ```
1548 | 
1549 | * Do not use the shorthand `transform` property to `rotate`, `scale`, or `translate` as these keywords have their own properties
1550 | * This allows you to animate and transition individual properties
1551 | * Continue using `transform` to use the `matrix` and `skew` keywords
1552 | 
1553 | ### `transition`
1554 | 
1555 | #### Don't
1556 | 
1557 | ```scss
1558 | .foo {
1559 |   transition: ease opacity 0.4s 0.2s;
1560 | }
1561 | ```
1562 | 
1563 | #### Do
1564 | 
1565 | ```scss
1566 | .foo {
1567 |   @include transition(opacity)
1568 | }
1569 | ```
1570 | 
1571 | * Use the `transition` mixin
1572 | * See the `get-transition-properties` function for default values used for timing and ease
1573 | * You can customise on a per mixin basis
1574 | 
1575 | ```scss
1576 | .foo {
1577 |   @include transition(transform var(--timing-slow) var(--easing-normal))
1578 | }
1579 | ```
1580 | 
1581 | * Do not transition `margin` or positional properties (`top`, `left`, `right`, `bottom`) as these don't perform well and lead to poor frame rates
1582 | * Instead use `padding` or `translate` as these can be hardware-accelerated
1583 | 
1584 | [ꜛ Back to TOC](#table-of-contents)
1585 | 


--------------------------------------------------------------------------------
/frame/README.md:
--------------------------------------------------------------------------------
 1 | <p align="center"><img src="https://raw.githubusercontent.com/we-make-websites/wmw-coding-guidelines/master/assets/logo.png" alt="We Make Websites" width="170"></p>
 2 | 
 3 | # Coding Guidelines
 4 | Deprecated. See [CANVAS guidelines](/README.md).
 5 | 
 6 | Standards, guidelines, and best practice we follow whilst developing at [We Make Websites](https://wemakewebsites.com/) on our FRAME framework.
 7 | 
 8 | ## Table of contents
 9 | 
10 | * [HTML](html/README.md)
11 | * [Liquid](liquid/README.md)
12 | * [CSS/SCSS](css/README.md)
13 | * [JavaScript](https://github.com/Shopify/javascript#import-javascript-from-shopify)
14 | * [VS Code](vs-code/README.md)
15 | 
16 | ## Why do we need guidelines?
17 | 
18 | When working on large, long-running projects, with dozens of developers of differing specialities and abilities, it is important that we all work in a unified way in order to:
19 | 
20 | * Keep the code base maintainable
21 | * Keep code transparent, sane, and readable
22 | * Keep the code base scalable
23 | * Maintain the code base's performance
24 | 
25 | ## Applying the guidelines
26 | 
27 | When you are writing new code you are expected to maintain the guidelines, if you update an existing feature you are expected to update any non-adhering code that you interact with or change. This means you are not expected to fix the whole file when adding new functionality, just the code you write or change.
28 | 
29 | ### FRAME 3
30 | When committing your changes the SCSS and JS files will be automated linted due to `husky` and `lint-staged`. You will have to manually apply the guidelines to HTML and Liquid as there is no linter available.
31 | 
32 | > **🗒 Note:** The oldest FRAME 3 projects will not adhere to the new HTML and Liquid guidelines as the guidelines were written after FRAME 3 was launched.
33 | 
34 | ### FRAME 1 & 2
35 | You must apply all guidelines manually; there is no automatic linting available.
36 | 


--------------------------------------------------------------------------------
/frame/css/README.md:
--------------------------------------------------------------------------------
   1 | # CSS Guidelines
   2 | 
   3 | ## stylelint & NPM
   4 | 
   5 | There is an NPM module available to import our CSS guidelines into stylelint. Simply use `yarn add @we-make-websites/stylelint-config` to install (Frame 3 already includes this package).
   6 | 
   7 | Visit [@we-make-websites/stylelint-config](https://www.npmjs.com/package/@we-make-websites/stylelint-config) or the [repo](https://github.com/we-make-websites/stylelint-config) for more information.
   8 | 
   9 | ## Table of contents
  10 | 
  11 | 1. [General](#general)
  12 | 1. [Methods](#methods)
  13 | 1. [Declarations](#declarations)
  14 | 1. [Naming](#naming)
  15 | 1. [Spacing](#spacing)
  16 | 1. [Formatting](#formatting)
  17 | 1. [Colours](#colours)
  18 | 1. [Nesting](#nesting)
  19 | 1. [Properties](#properties)
  20 | 
  21 | [← Back to homepage](../README.md)
  22 | 
  23 | ## General
  24 | 
  25 | * [DRY (Don't Repeat Yourself)](#dry-dont-repeat-yourself)
  26 | * [Notes on Frame](#notes-on-frame)
  27 | 
  28 | ### [DRY (Don't Repeat Yourself)](#dry-dont-repeat-yourself)
  29 | 
  30 | #### Don't
  31 | ```scss
  32 | .foo {
  33 |   background-color: #fff;
  34 |   border: 1px solid #000;
  35 |   color: #000;
  36 | }
  37 | 
  38 | .bar {
  39 |   background-color: #fff;
  40 |   border: 1px solid #000;
  41 |   color: #000;
  42 | }
  43 | ```
  44 | 
  45 | #### Do
  46 | ```scss
  47 | .btn {
  48 |   background-color: rgb(255, 255, 255);
  49 |   border: 1px solid rgb(0, 0, 0);
  50 |   color: rgb(0, 0, 0);
  51 | }
  52 | ```
  53 | 
  54 | * Keep things DRY, aim to use standard classes to so you can re-use your code
  55 | * SCSS includes and extends can encourage poor coding practice, just because it's one line in your code doesn't mean it is when exported
  56 | * If you're applying the same include or styles on lots of selectors, create a class and apply it in HTML to keep things DRY
  57 | * This is where defined h1, h2, p etc. in Sketch files would be really useful so we can re-use established styles
  58 | 
  59 | > **❗Exception:** Sometimes it's still better to KISS (Keep It Simple, Stupid) than DRY.
  60 | 
  61 | ### [Notes on Frame](#notes-on-frame)
  62 | 
  63 | #### Frame 3
  64 | You are expected to follow the guidelines to the letter without fail, Frame 3 represents the best that We Make Websites produces so your code should be too. Frame 3 comes with a style lint which will highlight errors, using yarn format will automatically fix most of these errors for you.
  65 | 
  66 | #### Frame 2
  67 | When building a new project using Frame 2.0 it is expected that if you build any new sections or re-build existing templates you will follow these guidelines.
  68 | 
  69 | #### Frame 1 and Old Workflow
  70 | Not all of these guidelines will be possible when working with an existing site (or any site built before these guidelines). Frame 2.0 local concatenation of code allows us to use SCSS features that are not available with Shopify's old version of SCSS, these should be highlighted in the Notes or Exceptions are the end of the page.
  71 | 
  72 | [ꜛ Back to TOC](#table-of-contents)
  73 | 
  74 | ## Methods
  75 | 
  76 | * [Mobile first](#mobile-first)
  77 | * [Responsive banner padding](#responsive-banner-padding)
  78 | * [Fullscreen elements](#fullscreen-elements)
  79 | * [Magic numbers](#magic-numbers)
  80 | 
  81 | ### [Mobile first](#mobile-first)
  82 | 
  83 | #### Don't
  84 | ```scss
  85 | .foo {
  86 |   // Desktop code
  87 | 
  88 |   @media (max-width: 768px) {
  89 |     // Mobile code
  90 |   }
  91 | }
  92 | ```
  93 | 
  94 | ### Do
  95 | ```scss
  96 | .foo {
  97 |   // Mobile code
  98 | 
  99 |   @media (min-width: 768px) {
 100 |     // Desktop code
 101 |   }
 102 | }
 103 | ```
 104 | 
 105 | * We should always develop mobile first
 106 | * This means we're expanding to fill desktop instead of cramming things in to fit mobile
 107 | * If we miss styling something the site will still be usable
 108 | 
 109 | ### [Responsive banner padding](#responsive-banner-padding)
 110 | 
 111 | #### Don't
 112 | ```scss
 113 | .foo {
 114 |   padding-top: 60%;
 115 | }
 116 | ```
 117 | 
 118 | #### Do
 119 | ```scss
 120 | .foo {
 121 |   // 16:9 ratio
 122 |   padding-bottom: 56.25%
 123 | }
 124 | ```
 125 | 
 126 | * When using padding to create a responsive banner always use padding-bottom
 127 | * Also add a preceding comment explaining the ratio of the banner
 128 | 
 129 | ### [Fullscreen elements](#fullscreen-elements)
 130 | 
 131 | #### Don't
 132 | ```scss
 133 | .foo {
 134 |   bottom: 0;
 135 |   left: 0;
 136 |   position: absolute;
 137 |   right: 0;
 138 |   top: 0;
 139 | }
 140 | ```
 141 | 
 142 | #### Do
 143 | ```scss
 144 | .foo {
 145 |   height: 100%;
 146 |   left: 0;
 147 |   position: absolute;
 148 |   top: 0;
 149 |   width: 100%;
 150 | }
 151 | ```
 152 | 
 153 | * Don't define all four positioning properties to set an element to fullscreen as these do not work on button elements
 154 | * Instead use `height: 100%` and `width: 100%`
 155 | 
 156 | ### [Magic numbers](#magic-numbers)
 157 | 
 158 | #### Don't
 159 | ```scss
 160 | .foo {
 161 |   left: 23px;
 162 | }
 163 | ```
 164 | 
 165 | #### Do
 166 | ```scss
 167 | .foo {
 168 |   // 10px because of font height
 169 |   left: ($GUTTER - 10px - ($NAV_HEIGHT / 2));
 170 | }
 171 | ```
 172 | 
 173 | #### If you have to
 174 | ```scss
 175 | .foo {
 176 |   // This values matches the sum of widths above it
 177 |   left: 23px;
 178 | }
 179 | ```
 180 | 
 181 | * Avoid magic numbers, these are numbers that 'just work' but are set arbitrarily
 182 | * Try and use calculations to make the values relative to existing known numbers
 183 | * When someone else comes to edit they won't understand why it's this number specifically
 184 | * If you have to; leave a comment explaining why that number, it can be just because it works, but explain what will break if it's changed
 185 | 
 186 | > **🗒 Note:** Read more on [CSS tricks](https://css-tricks.com/magic-numbers-in-css/).
 187 | 
 188 | [ꜛ Back to TOC](#table-of-contents)
 189 | 
 190 | ## Declarations
 191 | 
 192 | * [#IDs](#ids)
 193 | * [!important](#important)
 194 | * [Longhand properties](#longhand-properties)
 195 | * [Prefixes](#prefixes)
 196 | * [Property order](#property-order)
 197 | * [Pseudo-elements & -selectors](#pseudo-elements-&--selectors)
 198 | * [Variables](#variables)
 199 | 
 200 | ### [#IDs](#ids)
 201 | 
 202 | #### Don't
 203 | ```scss
 204 | #foo {
 205 |   #bar {
 206 |      background-color: #000;
 207 |   }
 208 | }
 209 | ```
 210 | 
 211 | #### Do
 212 | ```scss
 213 | .foo {
 214 |   .bar {
 215 |      background-color: rgb(0, 0, 0);
 216 |   }
 217 | }
 218 | ```
 219 | 
 220 | * Don't use IDs, ever. Definitely never use them nested under each other
 221 | * They're overly specific and trump classes in the order of CSS rendering
 222 | 
 223 | > **❗Exception:** Sometimes you may have to because you're working with apps or code you can't otherwise edit. In this case, and only as a last resort, use IDs.
 224 | 
 225 | ### [!important](#important)
 226 | 
 227 | #### Don't
 228 | ```scss
 229 | .foo {
 230 |   color: red !important;
 231 | }
 232 | ```
 233 | 
 234 | * Never use `!important` if it can be avoided
 235 | *  Add inline comments above the property explaining why if you have to use `!important`
 236 | 
 237 | > **❗Exception:** Sometimes you have to because of apps though. However before using !important consider doubling the specificity (see below) if you're battling code that is loaded in the page after your stylesheet but not actually inline.
 238 | 
 239 | #### Doubling Specificity
 240 | 
 241 | ```scss
 242 | .foo.foo {
 243 |   // This style will override .foo styles
 244 | }
 245 | ```
 246 | 
 247 | * This works because it's more specific than just the class name once, but won't override inline styles
 248 | * [Read this article](https://www.smashingmagazine.com/2007/07/css-specificity-things-you-should-know/) to find out more information about CSS specificity
 249 | 
 250 | ### [Longhand properties](#longhand-properties)
 251 | 
 252 | #### Don't
 253 | ```scss
 254 | .foo {
 255 |   background: url('/path/to/image.jpg') no-repeat 50% 50% #fff;
 256 |   font: 2rem/1.6 'Helvetica', sans-serif;
 257 | }
 258 | ```
 259 | 
 260 | #### Do
 261 | ```scss
 262 | .foo {
 263 |   background-color: #fff;
 264 |   background-image: url('/path/to/image.jpg');
 265 |   background-position: 50% 50%;
 266 |   background-repeat: no-repeat;
 267 |   font-family: 'Helvetica', sans-serif;
 268 |   font-size: 2rem;
 269 |   line-height: 1.6;
 270 | }
 271 | ```
 272 | 
 273 | * Avoid shorthand for background and font properties
 274 | * For these properties the non-described properties automatically are set to none/default/0 which causes issues
 275 | * The code is more verbose when making responsive changes
 276 | * Do not nest properties (used to be accepted, it no longer is)
 277 | 
 278 | > **❗Exception:** Feel free to use shorthand properties for `margin`, `padding`, `border`, and `transform`.
 279 | 
 280 | ### [Prefixes](#prefixes)
 281 | 
 282 | #### Frame 2 and 3
 283 | Thanks to the Frame 2 and 3 watch command you don't need to add prefixes to CSS properties as these are added automatically before upload.
 284 | 
 285 | #### Frame 1 and Old Workflow
 286 | 
 287 | If you're using the Old Workflow or Frame 1 you will need to add prefixes, you can keep track of browser support using [Can I Use](https://caniuse.com/). The most commonly needed prefixes is for Flex properties, use [Should I Prefix](http://shouldiprefix.com/) to find out what prefixes you need.
 288 | 
 289 | You will also need to add prefixes even if you're working on a Frame 2 or 3 project and not working on one of the bundled CSS files (like `checkout.scss.liquid`)
 290 | 
 291 | ### [Property order](#property-order)
 292 | 
 293 | #### Do
 294 | ```scss
 295 | .foo {
 296 |   // Extends
 297 |   @extend .grid;
 298 |   // Includes
 299 |   @include transition(0.5s);
 300 |   // Properties in alphabetical order
 301 |   // Frame 2+ auto-prefixes so no need to include them
 302 |   // Otherwise prefixed versions are listed under the main property
 303 |   background-color: transparent;
 304 |   border: 0;
 305 |   display: flex;
 306 |   display: -ms-flexbox;
 307 |   display: -webkit-flex;
 308 |   padding: 0;
 309 | 
 310 |   // Pseudo-element
 311 |   &::before {
 312 |     content: '';
 313 |   }
 314 | 
 315 |   // Nested elements
 316 |   &__bar {
 317 |     margin: 0;
 318 |   }
 319 | 
 320 |   // Direct descendents
 321 |   > .baz {
 322 |     padding: 0;
 323 |   }
 324 | 
 325 |   // Sibling selectors
 326 |   + .bam,
 327 |   ~ .bam {
 328 |     padding-left: 0;
 329 |   }
 330 | 
 331 |   // Pseudo-selectors
 332 |   &:focus, &:hover {
 333 |     box-shadow: 0 0 5px color(blue, 0.3);
 334 |   }
 335 | 
 336 |   // Modifiers
 337 |   &#{&}--big {
 338 |     width: 100%;
 339 |   }
 340 | 
 341 |   // Parents
 342 |   .parent & {
 343 |     display: none;
 344 |   }
 345 | }
 346 | ```
 347 | 
 348 | The order should be as follows, all items within each group should be sorted alphabetically:
 349 | 1. Local variables (e.g. `$local_margin`)
 350 | 1. Extends (e.g. `@extend %font`)
 351 | 1. Includes (e.g. `@include ms-respond()`)
 352 | 1. Properties (e.g. `background-color`)
 353 | 1. Pseudo-elements (e.g. `&::before`, `&::placeholder` etc.)
 354 | 1. Nested elements (e.g. `&__bar`)
 355 | 1. Direct descendants (e.g. `> .baz`, `+ .baz`)
 356 | 1. Pseudo-selectors (e.g. `&:hover`), this way they can change nested elements
 357 | 1. Modifiers (e.g. `&#{&}--big`), this gives them precedence over all nested elements
 358 | 1. Parents (e.g. `.parent &`), so that they have the greatest priority
 359 | 1. Media queries (e.g. `@include mq($from: large)`)
 360 | 
 361 | ### [Pseudo-elements & -selectors](#pseudo-elements-&--selectors)
 362 | 
 363 | #### Don't
 364 | ```scss
 365 | .foo {
 366 |   &:placeholder {}
 367 | 
 368 |   &:after {}
 369 | }
 370 | ```
 371 | 
 372 | #### Do
 373 | ```scss
 374 | .foo {
 375 |   &::after {}
 376 | 
 377 |   &::placeholder {}
 378 | 
 379 |   &:hover {}
 380 | }
 381 | ```
 382 | 
 383 | * Pseudo-elements should use `::` (after, before, first-letter, first-line, marker, placeholder, and selection)
 384 | * Pseudo-selectors should use `:` (hover, focus, active, nth-child etc.)
 385 | * This helps differentiate between an element and a selector
 386 | 
 387 | ### [Variables](#variables)
 388 | 
 389 | When first setting up your project you should go through and define a series of variables and mixins to help with the maintenance of the project, it's a lot easier to change the property of one variable rather than hunting for all appearances of, say, a `font-family`.
 390 | 
 391 | > **🗒 Note:** On Frame 3 projects you can use the styleguide page template.
 392 | 
 393 | It is the project lead developer's responsibility to set them up to maintain conformity.
 394 | 
 395 | Common properties that benefit from variables are:
 396 | * `border-radius`
 397 | * `color`
 398 | * `font-family`
 399 | * `font-weight`
 400 | * `margin` (gutters, grid gutters)
 401 | * `transition` (duration, easing) – consider a mixin
 402 | 
 403 | [ꜛ Back to TOC](#table-of-contents)
 404 | 
 405 | ## Naming
 406 | 
 407 | * [BEM & CSS](#bem-&-css)
 408 | * [BEM modifiers](#bem-modifiers)
 409 | * [BEM naming](#bem-naming)
 410 | * [HTML naming](#html-naming)
 411 | * [Descriptive naming](#descriptive-naming)
 412 | * [Variable naming](#variable-naming)
 413 | 
 414 | ### [BEM & CSS](#bem-&-css)
 415 | 
 416 | #### About
 417 | 
 418 | **BEM** stands for Block Element Modifier and is a element class naming convention intended to standardise the way elements are named so everyone is on the same page and can work out the relationship of elements without having to refer back to the HTML constantly. For more information go to [Get BEM](http://getbem.com/).
 419 | 
 420 | Below is an ideal example of how BEM would be used across HTML and CSS (technically SCSS).
 421 | 
 422 | #### HTML
 423 | This HTML example also includes a suggested way of targeting elements in JavaScript (`js-click`).
 424 | 
 425 | ```html
 426 | <div class="product">
 427 |   <h1 class="product__title"></h1>
 428 |   <h2 class="product__subtitle"></h2>
 429 | 
 430 |   <div class="product__image-container">
 431 |     <img src="" class="product__image" alt="" js-click="zoom-image">
 432 |     <!-- Suggest adding srcset and sizes for responsive images -->
 433 |   </div>
 434 | 
 435 |   <div class="product__description">
 436 |     <ul class="product-icons">
 437 |       <li class="product-icons__icon"><li>
 438 |       <li class="product-icons__icon"><li>
 439 |       <li class="product-icons__icon product-icons__icon--large"><li>
 440 |     </ul>
 441 |     <!-- Note how this is its own content block as .product__description__product-icons isn't valid BEM -->
 442 |     <!-- If you find yourself thinking you need to nest blocks within blocks then instead make a new container -->
 443 |     <!-- Also note that when using modifying classes you must still include the base non-modified classes -->
 444 |   </div>
 445 | </div>
 446 | 
 447 | <!-- Separate page -->
 448 | <div class="product-card">
 449 |   <ul class="product-icons">
 450 |     <li class="product-icons__icon"><li>
 451 |     <li class="product-icons__icon"><li>
 452 |     <li class="product-icons__icon product-icons__icon--large"><li>
 453 |   </ul>
 454 | </div>
 455 | ```
 456 | 
 457 | #### CSS
 458 | The below example will only work when you are using Frame 2 or higher as previous versions do not support interpolation brackets used in the class name.
 459 | 
 460 | ```scss
 461 | // Newlines and spacing removed for brevity
 462 | 
 463 | .product {
 464 |   &__title {}
 465 |   &__subtitle {}
 466 |   &__image-container {}
 467 |   &__image {}
 468 |   &__description {}
 469 | 
 470 |   // Even without comments we can see what we're editing
 471 |   // It doesn't matter if subtitle becomes another element for example
 472 | }
 473 | 
 474 | .product-icons {
 475 |   &__icon {
 476 |     &#{&}--large {
 477 |       // Also we're already at three levels deep so always keep an eye on your nesting
 478 |     }
 479 |   }
 480 | 
 481 |   .product-card & {
 482 |     // Keep all the code for .product-icons in one place by qualifying its context
 483 |     // Code here will only apply to .product-icons when inside .product-card
 484 |   }
 485 | }
 486 | ```
 487 | 
 488 | ### [BEM modifiers](#bem-modifiers)
 489 | 
 490 | #### Don't
 491 | ```html
 492 | <div class="bad"></div>
 493 | <div class="bad--modifier"></div>
 494 | ```
 495 | ```scss
 496 | .bad {
 497 |   &--modifier {}
 498 | }
 499 | ```
 500 | 
 501 | #### Do
 502 | ```html
 503 | <div class="good good--modifier"></div>
 504 | ```
 505 | ```scss
 506 | .good {
 507 |   &#{&}--modifier {}
 508 | }
 509 | ```
 510 | 
 511 | * Don't just apply the modifier class and extend the block/element class
 512 | * Apply the block/element as a class as well as the modifier class
 513 | 
 514 | ### [Concatenating](#concatenating)
 515 | 
 516 | #### Don't
 517 | ```scss
 518 | .foo {
 519 |   .foo__bar {
 520 |     .foo__bar--modifier {}
 521 |   }
 522 | }
 523 | ```
 524 | 
 525 | #### Do (Frame 2+ only)
 526 | ```scss
 527 | .foo {
 528 |   &__bar {
 529 |     &#{&}--modifier {}
 530 |   }
 531 | }
 532 | ```
 533 | 
 534 | * Keeps the BEM naming and nesting of selectors more obvious
 535 | * The modifier has interpolation brackets `#{}` because && is invalid SCSS
 536 | * The modifier would render as `.foo__bar.foo__bar--modifier` in CSS
 537 | * This means it has greater specificity, without this any later changes to .foo__bar would override the modifier (for example in media queries) as `.foo__bar` and `.foo__bar--modifier` would have the same specificity so the properties appear later would trump the modifier's
 538 | 
 539 | > **❗Exception:** If you're working on a site using the Old Workflow or Frame 1.0 this can't be done as Shopify's version of SCSS doesn't support concatenating or interpolation brackets.
 540 | 
 541 | ### [BEM naming](#bem-naming)
 542 | 
 543 | #### Don't
 544 | ```scss
 545 | .site-search {}
 546 | .site-search label {}
 547 | .site-search input {}
 548 | ```
 549 | 
 550 | #### Do
 551 | ```scss
 552 | .site-search {}
 553 | .site-search__title {}
 554 | .site-search__field {}
 555 | ```
 556 | 
 557 | * Elements may change and no longer be a label or input, breaking the CSS, causing maintenance issues so always select with a class
 558 | * With decent BEM naming you shouldn't need to comment your CSS to say what things are or where they sit
 559 | 
 560 | > **❗Exception:** Feel free to write comments to explain why you've done things strangely if you have had to.
 561 | 
 562 | ### [HTML naming](#html-naming)
 563 | 
 564 | #### Don't
 565 | ```scss
 566 | h3.foo {
 567 |   font-size: 2rem;
 568 | }
 569 | ```
 570 | 
 571 | #### Do
 572 | ```scss
 573 | .header__subtitle {
 574 |   font-size: 2rem;
 575 | }
 576 | ```
 577 | 
 578 | * Don't use the HTML element name to select an element
 579 | * Makes maintenance easier, if you change the HTML element you have to change it in the CSS too
 580 | * BEM naming should make it clear what you're selecting
 581 | 
 582 | ### [Descriptive naming](#descriptive-naming)
 583 | 
 584 | #### Don't
 585 | ```scss
 586 | .curley-font {
 587 |   font-family: 'Lobster', serif;
 588 | }
 589 | 
 590 | .red {
 591 |   color: $COLOR_RED;
 592 | }
 593 | ```
 594 | 
 595 | #### Do
 596 | ```scss
 597 | .blog__subtitle {
 598 |   font-family: 'Lobster', serif;
 599 | }
 600 | 
 601 | .u-highlight {
 602 |   color: $COLOR_RED;
 603 | }
 604 | ```
 605 | 
 606 | * CSS selectors should describe hierarchy, not the look as the look can change
 607 | 
 608 | ### [Variable naming](#variable-naming)
 609 | 
 610 | #### Don't
 611 | ```scss
 612 | $foo: 20px;
 613 | 
 614 | .foo {
 615 |   $foo-bar: (2 * $GRID_MARGIN);
 616 |   margin-left: $local_margin
 617 | }
 618 | ```
 619 | 
 620 | #### Do
 621 | ```scss
 622 | $GRID_MARGIN: 20px;
 623 | 
 624 | .foo {
 625 |   $local_margin: (2 * $GRID_MARGIN);
 626 |   margin-left: $local_margin
 627 | }
 628 | ```
 629 | 
 630 | * For global variables use SCREAMING_SNAKE_CASE
 631 | * For local variables use snake_case
 632 | 
 633 | > **🗒 Note:** Local variables are only available in the declaration they are defined in.
 634 | 
 635 | [ꜛ Back to TOC](#table-of-contents)
 636 | 
 637 | ## Spacing
 638 | 
 639 | * [Indenting](#indenting)
 640 | * [Whitespace](#whitespace)
 641 | 
 642 | ### [Indenting](#indenting)
 643 | 
 644 | #### Don't
 645 | ```scss
 646 | .foo {
 647 |     color: red;
 648 | 
 649 |     &_bar {
 650 |         // No good
 651 |     }
 652 | }
 653 | ```
 654 | 
 655 | #### Do
 656 | ```scss
 657 | .foo {
 658 |   color: red;
 659 | 
 660 |   &_bar {
 661 |     // Better
 662 |   }
 663 | }
 664 | ```
 665 | 
 666 | * Indent with 2 spaces, not tabs or 4 spaces
 667 | * Shopify uses 2 spaces
 668 | * Using spaces is easier to copy and paste
 669 | 
 670 | ### [Whitespace](#whitespace)
 671 | 
 672 | #### Don't
 673 | ```scss
 674 | .foo{box-shadow: 0 0 rgba(0,0,0,0.5);color:red;font:{size:1em;weight:700;}}
 675 | 
 676 | .foo,.spanner,.foobar{
 677 |   color:red;
 678 |   .baz{color:blue}}
 679 | 
 680 | .foo>.bar {color:red;}
 681 | ```
 682 | 
 683 | #### Do
 684 | ```scss
 685 | .foo {
 686 |   box-shadow: 0 0 rgba(0, 0, 0, 0.5);
 687 |   color: rgb(255, 0, 0);
 688 |   font-size: 1rem;
 689 |   font-weight: 700;
 690 | }
 691 | 
 692 | .foo, .foobar,
 693 | .spanner {
 694 |   color: rgb(0, 255, 0);
 695 | 
 696 |   .baz {
 697 |     color: rgb(0, 0, 255);
 698 |   }
 699 | }
 700 | 
 701 | .foo > .bar {
 702 |   color: rgb(255, 0, 0);
 703 | }
 704 | ```
 705 | 
 706 | * Add whitespace after commas (including property values), after selector name, after property colon and before and after child selector
 707 | * Each element selector block should have an empty line above it
 708 | * Each property on a new line and a new line for the closing }
 709 | * Keep related selectors on the same line, separate selectors go on a new line
 710 | * Add spaces between child selectors
 711 | * Put a semi-colon after a property, even if it's the last one
 712 | * Put a newline after the last selector
 713 | 
 714 | #### Why
 715 | * It's easier to read
 716 | * Whitespace is free
 717 | * Code is minified anyway
 718 | 
 719 | [ꜛ Back to TOC](#table-of-contents)
 720 | 
 721 | ## Formatting
 722 | 
 723 | * [Calculations](#calculation)
 724 | * [Capitalisation](#capitalisation)
 725 | * [Commenting (inline)](#commenting-inline)
 726 | * [Commenting (introductory)](#commenting-introductory)
 727 | * [Zero values & units](#zero-values-&-units)
 728 | * [Parenthesise on @includes](#parenthesise-on-includes)
 729 | 
 730 | ### [Calculations](#calculation)
 731 | 
 732 | #### Don't
 733 | ```scss
 734 | .foo {
 735 |   left: calc(100% - 30px * 2);
 736 |   width: 100% / 3;
 737 | }
 738 | ```
 739 | 
 740 | #### Do
 741 | ```scss
 742 | .foo {
 743 |   left: calc(100% - (#{$GUTTER} * 2));
 744 |   width: (100% / 3);
 745 | }
 746 | ```
 747 | 
 748 | * Wrap calculations in brackets for readability
 749 | * Put spaces between the values and the mathematical operators
 750 | * Put multiplying and dividing values after the starting value
 751 | 
 752 | #### Also
 753 | ```scss
 754 | .foo {
 755 |   $local_margin: (2 * $GLOBAL_MARGIN);
 756 | 
 757 |   margin-bottom: $local_margin;
 758 |   width: calc(100% + #{$local_margin});
 759 | }
 760 | ```
 761 | 
 762 | * Use local variables to define adjusted global variables
 763 | 
 764 | ### [Capitalisation](#capitalisation)
 765 | 
 766 | #### Don't
 767 | ```scss
 768 | .Foo {
 769 |   Background: $color_Blue;
 770 | }
 771 | ```
 772 | 
 773 | #### Do
 774 | ```scss
 775 | .foo {
 776 |   background: $COLOR_CORNFLOWER_BLUE;
 777 | }
 778 | ```
 779 | 
 780 | * Use lowercase for selectors and properties
 781 | * Refer to [Variable naming](#variable-naming) for global and local variables
 782 | 
 783 | ### [Commenting (inline)](#commenting-inline)
 784 | 
 785 | #### Don't
 786 | ```scss
 787 | .foo {
 788 |   background-color: red; // Don't
 789 |   /* padding-top: 30px;
 790 |   width: 100% */
 791 | }
 792 | ```
 793 | 
 794 | #### Do
 795 | ```scss
 796 | .foo {
 797 |   // Comment above the line
 798 |   background-color: red;
 799 |   // padding-top: 30px;
 800 |   // width: 100%;
 801 | }
 802 | ```
 803 | 
 804 | * Use `//` for commenting not the block level `/* */`
 805 | * It's easier to un-comment
 806 | * Inline comments should start on a new line preceding the property they're describing
 807 | * Use sentence case for your comments
 808 | * Do not end with a full stop
 809 | 
 810 | ### [Commenting (introductory)](#commenting-introductory)
 811 | 
 812 | ```css
 813 | /**
 814 |  * Component: Footer Social
 815 |  * -----------------------------------------------------------------------------
 816 |  * Social icons and links in footer.
 817 |  *
 818 |  */
 819 | ```
 820 | 
 821 | * Include an introductory comment at the start of each file
 822 | * Describe what folder it's in, the file's name, and list any special features or conditions
 823 | * All lines except the first one should have a full stop
 824 | 
 825 | ### [Zero values & units](#zero-values-&-units)
 826 | 
 827 | #### Don't
 828 | ```scss
 829 | .foo {
 830 |   animation-delay: 0;
 831 |   margin: 0px;
 832 |   opacity: .4567;
 833 | }
 834 | ```
 835 | 
 836 | #### Do
 837 | ```scss
 838 | .foo {
 839 |   animation-delay: 0s;
 840 |   margin: 0;
 841 |   opacity: 0.4;
 842 | }
 843 | ```
 844 | 
 845 | * Do specify units on zero duration times
 846 | * Don't specify units on zero length values
 847 | * Do add a leading zero for decimal places
 848 | * Don't go to more than three decimal places, the fewer the better
 849 | 
 850 | ### [Parenthesise on @includes](#parenthesise-on-includes)
 851 | 
 852 | #### Where
 853 | ```scss
 854 | @mixin animation($property: color) {
 855 |   // Code
 856 | }
 857 | 
 858 | @mixin visually-hidden() {
 859 |   // Code
 860 | }
 861 | ```
 862 | 
 863 | #### Don't
 864 | ```scss
 865 | .foo {
 866 |   @include animation(background-color);
 867 |   @include visually-hidden();
 868 | }
 869 | ```
 870 | 
 871 | #### Do
 872 | ```scss
 873 | .foo {
 874 |   @include animation(background-color);
 875 |   @include visually-hidden;
 876 | }
 877 | ```
 878 | 
 879 | * Do not include parenthesise on argument-less mixins
 880 | 
 881 | [ꜛ Back to TOC](#table-of-contents)
 882 | 
 883 | ## Colours
 884 | 
 885 | * [Colour properties](#colour-properties)
 886 | * [Colour variables](#colour-variables)
 887 | 
 888 | ### [Colour properties](#colour-properties)
 889 | 
 890 | #### Don't
 891 | ```scss
 892 | .foo {
 893 |   color: RED;
 894 |   // Or
 895 |   color: #FF0000;
 896 |   // Or
 897 |   color: hsl(0, 100%, 50%);
 898 | }
 899 | ```
 900 | 
 901 | #### Do
 902 | ```scss
 903 | .foo {
 904 |   color: rgb(255, 0, 0);
 905 |   // Or
 906 |   color: rgba(255, 0, 0, 0.5);
 907 | }
 908 | ```
 909 | 
 910 | * Use RGB (or RGBA) colour values as they are more human readable
 911 | * These values are often supplied in brand guidelines
 912 | 
 913 | > **❗Exception:** If required, use lowercase and shorthand (where possible) hex colour values and names.
 914 | 
 915 | ### [Colour variables](#colour-variables)
 916 | 
 917 | #### Don't
 918 | ```scss
 919 | $colour-blue-other: #6195ed;
 920 | $colour-dark-grey: #E2E3E4;
 921 | $lighter-grey: #d4d7d9;
 922 | ```
 923 | 
 924 | #### Do
 925 | ```scss
 926 | $COLOR_CORNFLOWER_BLUE: rgb(97,149,237);
 927 | $COLOR_IRON_1: rgb(226,227,228);
 928 | $COLOR_IRON_2: rgb(212,215,217);
 929 | ```
 930 | 
 931 | * All colours should have variables defined for them, this will come from the design
 932 | * Use color as the prefix for your variables (not colour, this is consistent with the CSS spec)
 933 | * Colours are global variables so they should be in all caps
 934 | * Use [this website](http://chir.ag/projects/name-that-color/#6195ED) to automatically generate colour names (unless they're named in the client's brand guidelines)
 935 | * If you have two or more colours similar enough to share the same name then suffix them with a number where the 1 is the darkest variant of the colour
 936 | 
 937 | > **🗒 Note:** VS Code automatically previews the colour.
 938 | 
 939 | [ꜛ Back to TOC](#table-of-contents)
 940 | 
 941 | ## Nesting
 942 | 
 943 | * [Nesting levels](#nesting-levels)
 944 | * [Nesting media queries](#nesting-media-queries)
 945 | 
 946 | ### [Nesting levels](#nesting-levels)
 947 | 
 948 | #### Don't
 949 | ```scss
 950 | .foo {
 951 |   .this {
 952 |     .is {
 953 |       .very {
 954 |         .bad {
 955 | 
 956 |         }
 957 |       }
 958 |     }
 959 |   }
 960 | 
 961 |   @media (max-width: 700px) {
 962 |     .this .is .very .bad {
 963 | 
 964 |     }
 965 |   }
 966 | }
 967 | ```
 968 | 
 969 | #### Do
 970 | ```scss
 971 | .foo {
 972 |   // Base level (not included)
 973 | 
 974 |   &__bar {
 975 |     // Level one
 976 | 
 977 |     &:hover {
 978 |       // Level two
 979 | 
 980 |       &.bar {
 981 |         // Level three
 982 |       }
 983 |     }
 984 |   }
 985 | 
 986 |   @media (min-width: 700px) {
 987 |     // Base level (not included)
 988 | 
 989 |     &__bar {
 990 |       // Level one
 991 | 
 992 |       &:hover {
 993 |         // Level two
 994 | 
 995 |         &.bar {
 996 |           // Level three
 997 |         }
 998 |       }
 999 |     }
1000 |   }
1001 | }
1002 | ```
1003 | 
1004 | * Don't nest more than 3 levels
1005 | * Requires an even more specific selector to override it
1006 | * Mounts up to a significant maintenance issue
1007 | * This does mean that you can't always nest properties the way you normally would
1008 | * Media queries are not included when counting levels of nesting
1009 | 
1010 | > **🗒 Note:** VS Code shows you how many levels deep you are in its Breadcrumbs feature (View > Toggle Breadcrumbs). You should only ever see three stages after the base declaration.
1011 | 
1012 | ### [Nesting media queries](#nesting-media-queries)
1013 | 
1014 | #### Don't
1015 | ```scss
1016 | .foo {
1017 | 
1018 |   &__bar {
1019 |     // Code
1020 | 
1021 |     @media (min-width: 568px) {
1022 |       // Code
1023 |     }
1024 |   }
1025 | 
1026 |   &__section {
1027 |     // Code
1028 | 
1029 |     @media (min-width: 568px) {
1030 |       // Code
1031 |     }
1032 |   }
1033 | }
1034 | ```
1035 | 
1036 | #### Do
1037 | ```scss
1038 | .foo {
1039 | 
1040 |   &__bar {
1041 |     // Code
1042 |   }
1043 | 
1044 |   &__section {
1045 |     // Code
1046 |   }
1047 | 
1048 |   @media (min-width: 568px) {
1049 |     &__bar {
1050 |       // Code
1051 |     }
1052 | 
1053 |     &__section {
1054 |       // Code
1055 |     }
1056 |   }
1057 | }
1058 | ```
1059 | 
1060 | * Keep media queries at the root of the declaration, not nested inside each selector
1061 | * This way it's easier to find media queries
1062 | * Frame 2+ keeps CSS files small and modular so `@media`/`@include mq()` won't get lost
1063 | 
1064 | [ꜛ Back to TOC](#table-of-contents)
1065 | 
1066 | ## Properties
1067 | 
1068 | * [border](#border)
1069 | * [font-family](#font-family)
1070 | * [font-size](#font-size)
1071 | * [letter-spacing](#letter-spacing)
1072 | * [line-height](#line-height)
1073 | * [margin-top](#margin-top)
1074 | * [transition](#transition)
1075 | 
1076 | ### [border](#border)
1077 | 
1078 | #### Don't
1079 | ```scss
1080 | .foo {
1081 |   border: none;
1082 | }
1083 | ```
1084 | 
1085 | #### Do
1086 | ```scss
1087 | .bar {
1088 |   border: 2px solid rgb(0, 0, 0);
1089 | 
1090 |   &:hover {
1091 |     border-color: rgb(255, 255, 255);
1092 |   }
1093 | }
1094 | ```
1095 | 
1096 | * Use 0 instead of none for borders
1097 | * When a border is set to 0 it will never display, however if a border is set to none but later overridden by a border-style it will display
1098 | * If you're changing a single part of the property then target that specific property rather than setting all the properties again, this is much easier to maintain
1099 | 
1100 | ### [font-family](#font-family)
1101 | 
1102 | #### Don't
1103 | ```scss
1104 | .foo {
1105 |   font-family: 'Avenir';
1106 | }
1107 | ```
1108 | 
1109 | #### Do
1110 | ```scss
1111 | .foo {
1112 |   font-family: 'Avenir', Helvetica, Arial, sans-serif;
1113 | }
1114 | ```
1115 | 
1116 | * Don't only declare the custom font
1117 | * Always provide a font stack which includes web-safe fonts
1118 | * This prevents loading blank pages until the font loads
1119 | * The `font-family` should be declared in a variable, do not individually declare the `font-family`
1120 | 
1121 | ### [font-size](#font-size)
1122 | 
1123 | #### Don't
1124 | ```scss
1125 | .foo {
1126 |   font-size: 12px;
1127 | }
1128 | 
1129 | .bar {
1130 |   font-size: 1em;
1131 | }
1132 | ```
1133 | 
1134 | #### Do
1135 | ```scss
1136 | .foo {
1137 |   @include ms-respond(font-size, 1);
1138 |   // Or
1139 |   font-size: rem(18);
1140 |   // Or
1141 |   font-size: 1rem;
1142 | }
1143 | ```
1144 | 
1145 | * Use rem, relative ems. They're easier to understand as they're always relative to the base font-size
1146 | * Frame 3 comes with a responsive font `@mixin`, use this
1147 | * Most Frame 2 themes come with a REM function which lets your use pixel sizes
1148 | 
1149 | #### Don't
1150 | ```scss
1151 | .foo {
1152 |   font-size: 1.263rem;
1153 | }
1154 | ```
1155 | 
1156 | * This should be considered at the design phase but keep font sizes relative to each other in rational numbers
1157 | 
1158 | ### [letter-spacing](#letter-spacing)
1159 | 
1160 | #### Don't
1161 | ```scss
1162 | .foo {
1163 |   letter-spacing: 0.001rem;
1164 | }
1165 | 
1166 | .bar {
1167 |   letter-spacing: 0.02em;
1168 | }
1169 | ```
1170 | 
1171 | #### Do
1172 | ```scss
1173 | .foo {
1174 |   letter-spacing: 1px;
1175 | }
1176 | ```
1177 | 
1178 | * Use pixel values for `letter-spacing`
1179 | 
1180 | ### [line-height](#line-height)
1181 | 
1182 | #### Don't
1183 | ```scss
1184 | .foo {
1185 |   line-height: 18.5px;
1186 | }
1187 | 
1188 | .bar {
1189 |   line-height: 2.35rem;
1190 | }
1191 | ```
1192 | 
1193 | #### Do
1194 | ```scss
1195 | .foo {
1196 |   line-height: 1.6;
1197 | }
1198 | ```
1199 | 
1200 | * Use unit-less relative `line-height`
1201 | * This means `line-height` will scale with the font size rather than being fixed
1202 | * Another consideration at the design phase is to keep line height relative to the font size in rational numbers
1203 | 
1204 | ### [margin-top](#margin-top)
1205 | 
1206 | #### Don't
1207 | ```scss
1208 | .foo {
1209 |   margin-top: 30px;
1210 | }
1211 | ```
1212 | 
1213 | #### Do
1214 | ```scss
1215 | .bar {
1216 |   &:not(:last-child) {
1217 |     margin-bottom: 30px;
1218 |   }
1219 | }
1220 | ```
1221 | 
1222 | * Don't use margin-top to space elements out as vertical margins collapse
1223 | * Use padding-top or margin-bottom on preceding elements
1224 | 
1225 | > **❗Exception:**  When you need a negative `margin-top` or when the element is toggled below a preceding element so you don't have to add a `margin-bottom` to the preceding element and then toggle a class to remove it
1226 | 
1227 | ### [transition](#transition)
1228 | 
1229 | #### Don't
1230 | ```scss
1231 | .foo {
1232 |   transition: ease transform 0.4s 0.2s;
1233 | }
1234 | ```
1235 | 
1236 | #### Do
1237 | ```scss
1238 | .foo {
1239 |   transition: transform 0.4s ease 0.2s;
1240 |   will-change: transform
1241 | }
1242 | ```
1243 | 
1244 | * Make sure you put your transition properties in the correct order:
1245 | ```scss
1246 | transition: [transition-property] [transition-duration] [transition-timing-function] [transition-delay];
1247 | ```
1248 | * Use `will-change` to highlight to the browser that the property will change, this helps performance as the browser will then use hardware acceleration (not widely supported yet)
1249 | * Use this only when the transition is used frequently ie: navigation drawer
1250 | * Avoid overusing it as it could have the opposite effect and hinder all animations
1251 | 
1252 | > **⚠️ Important!** Do not transition `margin` or positional properties (`top`, `left`, `right`, `bottom`) as these don't perform well and lead to poor frame rates, instead use `padding` or `transform` as they can be hardware-accelerated.
1253 | 
1254 | [ꜛ Back to TOC](#table-of-contents)


--------------------------------------------------------------------------------
/frame/html/README.md:
--------------------------------------------------------------------------------
  1 | # HTML Guidelines
  2 | 
  3 | The below guidelines cover only specific scenarios and should not be considered exhaustive. For more general HTML guidelines visit [Google's HTML Style guide](https://google.github.io/styleguide/htmlcssguide.html).
  4 | 
  5 | **Where there are differences our guidelines take precedence.**
  6 | 
  7 | ## Table of contents
  8 | 
  9 | 1. [Attributes](#attributes)
 10 | 1. [Characters](#characters)
 11 | 1. [Commenting](#commenting)
 12 | 1. [`<div>` or `<span>`](#div-or-span)
 13 | 1. [Indenting](#indenting)
 14 | 1. [Spacing & line character limits](#spacing--line-character-limits)
 15 | 1. [Self-closing element](#self-closing-elements)
 16 | 
 17 | [← Back to homepage](../README.md)
 18 | 
 19 | ## Attributes
 20 | 
 21 | * [Attribute order](#attribute-order)
 22 | * [Attribute values](#attribute-values)
 23 | 
 24 | ### [Attribute order](#attribute-order)
 25 | 
 26 | #### Don't
 27 | ```html
 28 | <input id="NewsletterModal-Email" class="newsletter-modal__textarea" autocapitalize="off" autocomplete="newsletter-address" autocorrect="off" name="contact[email]" placeholder="{{ 'general.newsletter_form.email_placeholder' | t }}" type="email" value="{{ customer.email }}" aria-labelledby="NewsletterModal-EmailLabel" data-show="true" js-newsletter="email">
 29 | >
 30 | ```
 31 | 
 32 | #### Do
 33 | ```html
 34 | <input
 35 |   id="NewsletterModalEmail"
 36 |   class="newsletter-modal__textarea"
 37 |   autocapitalize="off"
 38 |   autocomplete="newsletter-address"
 39 |   autocorrect="off"
 40 |   name="contact[email]"
 41 |   placeholder="{{ 'general.newsletter_form.email_placeholder' | t }}"
 42 |   type="email"
 43 |   value="{{ customer.email }}"
 44 |   aria-labelledby="NewsletterModalEmailLabel"
 45 |   data-show="true"
 46 |   js-newsletter="email"
 47 | >
 48 | ```
 49 | 
 50 | * When an element has more than two attributes they should be stacked on newlines
 51 | * They should follow this order:
 52 |   * `id`
 53 |   * `class`
 54 |   * {native}
 55 |   * `aria-`
 56 |   * `data-`
 57 |   * `js-`
 58 | * {native} covers everything else, items within {native} should be in alphabetical order
 59 | * This makes it easier for managing merges in Git
 60 | * Make sure you trim trailing spaces after each line
 61 | 
 62 | > **🗒 Note:** Be sure to follow the formatting; the trailing `>` should be on a newline with the attributes indented in two spaces.
 63 | 
 64 | ### Also
 65 | ```html
 66 | <div class="hero template-article__hero-image lazyload" data-bgset="{% render 'responsive-bg-image' with image: article.image %}"></div>
 67 | 
 68 | <div
 69 |   class="hero template-article__hero-image lazyload"
 70 |   data-bgset="{% render 'responsive-bg-image' with image: article.image %}"
 71 | >
 72 | </div>
 73 | ```
 74 | 
 75 | * Use multi-line attributes if as a single line it would exceed 80 characters
 76 | 
 77 | ### [Attribute values](#attribute-values)
 78 | 
 79 | * `id` values should be PascalCase
 80 | * `class` values should follow BEM naming conventions
 81 | * `js-` attributes should be camelCase
 82 | 
 83 | [ꜛ Back to TOC](#table-of-contents)
 84 | 
 85 | ## [Characters](#characters)
 86 | 
 87 | ### Don't
 88 | ```html
 89 | <div class='foo'></div>
 90 | ```
 91 | 
 92 | ### Do
 93 | ```html
 94 | <div class="foo"></div>
 95 | ```
 96 | 
 97 | * Use quotations `"` HTML elements, not apostrophes `'`
 98 | 
 99 | [ꜛ Back to TOC](#table-of-contents)
100 | 
101 | ## [Commenting](#commenting)
102 | 
103 | ### Don't
104 | ```html
105 | <!-- Comment goes here -->
106 | ```
107 | 
108 | ### Do
109 | ```html
110 | {% comment %} Comment goes here {% endcomment %}
111 | ```
112 | 
113 | * Do not use HTML comments, use the `{% comment %}` filter with whitespace operators
114 | * Liquid `{% comment %}` will not be rendered in the HTML
115 | * Use spaces inside the `{% comment %}` tag
116 | 
117 | [ꜛ Back to TOC](#table-of-contents)
118 | 
119 | ## [`<div>` or `<span>`](#div-or-span)
120 | 
121 | `<div>` and `<span>` are often used interchangeably but there are specific use cases for each:
122 | 
123 | * If the content is going to be displayed inline, use `<span>`
124 | * If you want the element to display block, on its own line, use `<div>`
125 | * If you're using CSS to change its `display` property, consider using the other
126 | 
127 | [ꜛ Back to TOC](#table-of-contents)
128 | 
129 | ## [Indenting](#indenting)
130 | 
131 | ### Don't
132 | ```html
133 | <p class="body-1">
134 | {{ product.description }}
135 | </p>
136 | ```
137 | 
138 | ### Do
139 | ```html
140 | <p class="body-1">
141 |   {{ product.description }}
142 | </p>
143 | ```
144 | 
145 | * Indent two spaces inside each opening HTML element
146 | 
147 | [ꜛ Back to TOC](#table-of-contents)
148 | 
149 | ## [Spacing & line character limits](#spacing--line-character-limits)
150 | 
151 | ### Don't
152 | ```html
153 | <div id="Product" class="product" data-id="{{ product.id }}" js-product="container">
154 |   <h1 class="product__title">{{ product.title }}</h1>
155 |   <h2 class="product__subtitle">{{ product.type }}</h2>
156 |   <button class="product__button product-button"><span class="product-button__icon">{% render 'icon-misc' with icon: 'plus' %}</span><span class="product-button__text">{{ 'products.product.add_to_cart' | t }}</span></button>
157 |   <div class="product__content product-content">
158 |     <p class="product-content__description">{{ product.description }}</p>
159 |     <p class="product-content__shipping">{{ pages['shipping'].content | strip_html }}</p>
160 |   </div>
161 |   <div class="footer"><div class="footer__inner"><span class="footer__copy">{{ 'footer.copyright' | t }}</span><span class="footer__name">{{ shop.name }}</span><img src="{{ settings.logo | img_url: '300x' }}" alt="{{ settings.logo.alt }}"></div></div>
162 | </div>
163 | ```
164 | 
165 | ### Do
166 | ```html
167 | <div
168 |   id="Product"
169 |   class="product"
170 |   data-id="{{ product.id }}"
171 |   js-product="container"
172 | >
173 |   <h1 class="product__title">{{ product.title }}</h1>
174 |   <h2 class="product__subtitle">{{ product.type }}</h2>
175 | 
176 |   <button class="product__button product-button">
177 |     <span class="product-button__icon">
178 |       {% render 'icon-misc' with icon: 'plus' %}
179 |     </span>
180 | 
181 |     <span class="product-button__text">
182 |       {{ 'products.product.add_to_cart' | t }}
183 |     </span>
184 |   </button>
185 | 
186 |   <div class="product__content product-content">
187 |     <p class="product-content__description">
188 |       {{ product.description }}
189 |     </p>
190 | 
191 |     <div class="product-content__shipping">
192 |       {{ pages['shipping'].content }}
193 |     </div>
194 |   </div>
195 | 
196 |   <div class="footer">
197 |     <div class="footer__inner">
198 |       <span class="footer__copy">{{ 'footer.copyright' | t }}</span>
199 |       <span class="footer__name">{{ shop.name }}</span>
200 | 
201 |       <img
202 |         alt="{{ settings.logo.alt }}"
203 |         src="{{ settings.logo | img_url: '300x' }}"
204 |       >
205 |     </div>
206 |   </div>
207 | </div>
208 | ```
209 | 
210 | * Use common sense spacing to improve the readability of your code
211 | * [Block-level elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements) should open onto a new line and indent
212 | * [Inline-level elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#Elements) should be written on a single line
213 | * Single line elements should be grouped together by type
214 | * Multi-line elements should have a newline between them
215 | * This guideline includes empty block-level elements, e.g. the following is correct:
216 | 
217 | ```html
218 | <div
219 |   class="article__image"
220 |   data-bgset="{% render 'responsive-bg-image' with image: article.image %}"
221 |   js-article="image"
222 | ></div>
223 | ```
224 | 
225 | * Once you are writing something over multiple lines, each line should only have one attribute or value on it
226 | * If an attribute's value exceeds 80 characters then it should be split in the following format:
227 | 
228 | ```html
229 | <div
230 |   class="
231 |     class-1
232 |     class-2
233 |     class-3
234 |     class-4
235 |   "
236 |   data-handle="{{ product.handle }}"
237 |   js-product="content"
238 | >
239 |   <!-- Content -->
240 | </div>
241 | ```
242 | 
243 | ### Exceptions
244 | 
245 | * Short block-level elements like `<h1>`, `<li>` or `<title>` can be displayed on a single line unless they're greater than 80 characters long
246 | * Inline-level elements greater than 80 characters long should follow multi-line rules
247 | 
248 | [ꜛ Back to TOC](#table-of-contents)
249 | 
250 | ## [Self-closing elements](#self-closing-elements)
251 | 
252 | ### Don't
253 | ```html
254 | <img src="image.png" alt=""/>
255 | <input class="foo" placeholder="Content"/>
256 | ```
257 | 
258 | ### Do
259 | ```html
260 | <img src="image.png" alt="">
261 | <input class="foo" placeholder="Content">
262 | ```
263 | 
264 | * The `/` in self-closing tags is obsolete, do not use it
265 | 
266 | [ꜛ Back to TOC](#table-of-contents)


--------------------------------------------------------------------------------
/frame/liquid/README.md:
--------------------------------------------------------------------------------
  1 | # Liquid Guidelines
  2 | 
  3 | The below guidelines cover only specific scenarios and should not be considered exhaustive. For more general HTML guidelines visit [Shopify's Liquid file requirements for themes](https://help.shopify.com/en/themes/development/theme-store-requirements/theme-file-requirements).
  4 | 
  5 | **Where there are differences our guidelines take precedence.**
  6 | 
  7 | ## Shopify Cheatsheet
  8 | 
  9 | The [Shopify Cheatsheet](https://www.shopify.co.uk/partners/shopify-cheat-sheet) is no longer up-to-date. For a full and complete list of available objects, tags, and filters see the [Liquid reference](https://help.shopify.com/en/themes/liquid/objects) documentation.
 10 | 
 11 | ## Table of contents
 12 | 
 13 | 1. [Commenting](#commenting)
 14 | 1. [Conditional statements](#conditional-statements)
 15 | 1. [DRY (Don't Repeat Yourself)](#dry-dont-repeat-yourself)
 16 | 1. [Formatting](#formatting)
 17 | 1. [Language strings](#language-strings)
 18 | 1. [Naming](#naming)
 19 | 1. [Schema settings](#schema-settings)
 20 | 1. [Snippets](#snippets)
 21 | 1. [Split characters](#split-characters)
 22 | 1. [Variables](#variables)
 23 | 1. [Whitespace controls](#whitespace-controls)
 24 | 
 25 | [← Back to homepage](../README.md)
 26 | 
 27 | ## Commenting
 28 | 
 29 | * [Inline](#inline)
 30 | * [Introductory](#introductory)
 31 | 
 32 | ### [Inline](#inline)
 33 | 
 34 | #### Don't
 35 | ```html
 36 | <!-- Only display description if tag is present -->
 37 | {% if has_tag %}
 38 |   <div class="foo">{{ product.description }}</div>
 39 | {% endif %}
 40 | ```
 41 | 
 42 | #### Do
 43 | ```html
 44 | {% comment %} Only display description if tag is present {% endcomment %}
 45 | {% if has_tag %}
 46 |   <div class="foo">
 47 |     {{ product.description }}
 48 |   </div>
 49 | {% endif %}
 50 | ```
 51 | 
 52 | * Use the `{% comment %}` tag for inline comments, not HTML comments
 53 | * For `.js.liquid` or `.scss.liquid` file use the language appropriate comment
 54 | 
 55 | ### [Introductory](#introductory)
 56 | 
 57 | #### Do
 58 | ```html
 59 | {% comment %}
 60 | ------------------------------------------------------------------------------
 61 |   Section: Featured link
 62 |   - Used to display up to 2 images with text overlays with links.
 63 | ------------------------------------------------------------------------------
 64 | {% endcomment %}
 65 | ```
 66 | 
 67 | * Include an introductory comment at the start of each file
 68 | * Describe what folder it's in, the file's name, and list any special features or conditions
 69 | * If it's something included using a `{% render %}` then show an example with its variables, e.g.
 70 | ```html
 71 | {% comment %}
 72 | ------------------------------------------------------------------------------
 73 |   Snippet: Responsive image
 74 |   It creates a style tag and it restricts an image from growing larger than its max resolution.
 75 | 
 76 |   Usage:
 77 |   In your liquid template file, copy the following line
 78 |   - {% render 'responsive-image' with image: featured_image, image_class: "css-class", wrapper_class: "wrapper-css-class", max_width: 700, max_height: 800 %}
 79 | ------------------------------------------------------------------------------
 80 | {% endcomment %}
 81 | ```
 82 | 
 83 | [ꜛ Back to TOC](#table-of-contents)
 84 | 
 85 | ## Conditional statements
 86 | 
 87 | * [Conditional settings](#conditional-settings)
 88 | * [Conditional spacing](#conditional-spacing)
 89 | * [`{% if %}` or `{% case %}`](#-if--or--case-)
 90 | * [Inline `{% if %}` statements](#inline--if--statements)
 91 | 
 92 | ### [Conditional settings](#conditional-settings)
 93 | 
 94 | #### Don't
 95 | ```html
 96 | {% for block in section.blocks %}
 97 |   <div class="block">
 98 |     <img src="{{ block.settings.image | img_url: '2000x' }}" alt="{{ block.settings.image.alt }}">
 99 | 
100 |     <h2 class="block__title">{{ block.settings.title }}</h2>
101 |     <div class="block__text rte">{{ block.settings.text }}</div>
102 | 
103 |     <a class="block__button" href="{{ block.settings.button_url }}">
104 |       {{ block.settings.button_text }}
105 |     </a>
106 |   </div>
107 | {% endfor %}
108 | ```
109 | 
110 | #### Do
111 | ```html
112 | {% for block in section.blocks %}
113 |   <div class="block">
114 |     {% if block.settings.image != '' %}
115 |       <img
116 |         alt="{{ block.settings.image.alt }}"
117 |         src="{{ block.settings.image | img_url: '2000x' }}"
118 |       >
119 |     {% endif %}
120 | 
121 |     {% if block.settings.title != '' %}
122 |       <h2 class="block__title">{{ block.settings.title }}</h2>
123 |     {% endif %}
124 | 
125 |     {% if block.settings.text != '' %}
126 |       <div class="block__text rte">
127 |         {{ block.settings.text }}
128 |       </div>
129 |     {% endif %}
130 | 
131 |     {% if block.settings.button url != '' and block.settings.button_text != '' %}
132 |       <a class="block__button" href="{{ block.settings.button_url }}">
133 |         {{ block.settings.button_text }}
134 |       </a>
135 |     {% endif %}
136 |   </div>
137 | {% endfor %}
138 | ```
139 | 
140 | * In areas where the client can customise the content do not assume that they will want to display every part of a section's settings
141 | * Wrap each setting in a `{% if %}` to hide it if no content is entered
142 | * Use `!= ''` rather than `{% if condition %}` or `!= blank` as it is more reliable, it is possible for a setting to exist if it previously had a value
143 | * When testing make sure the section does not appear visually broken, the client will expect it to work with missing settings
144 | 
145 | ### [Conditional spacing](#conditional-spacing)
146 | 
147 | #### Don't
148 | ```html
149 | {% if condition %}
150 |   <!-- Multiple lines of code -->
151 |   <!-- Multiple lines of code -->
152 |   <!-- Multiple lines of code -->
153 | {% else %}
154 |   <!-- Multiple lines of code -->
155 |   <!-- Multiple lines of code -->
156 |   <!-- Multiple lines of code -->
157 | {% endif %}
158 | ```
159 | 
160 | #### Do
161 | ```html
162 | {% if condition %}
163 |   <!-- Multiple lines of code -->
164 |   <!-- Multiple lines of code -->
165 |   <!-- Multiple lines of code -->
166 | 
167 | {% else %}
168 |   <!-- Multiple lines of code -->
169 |   <!-- Multiple lines of code -->
170 |   <!-- Multiple lines of code -->
171 | {% endif %}
172 | ```
173 | 
174 | * When an `{% if %}` tag spans multiple lines add a newline before the `{% else %}` tag
175 | * This helps visually separate the code and make it easier to scan
176 | 
177 | ### [`{% if %}` or `{% case %}`](#-if--or--case-)
178 | 
179 | #### Don't
180 | ```html
181 | {% if variable == 'Hello' %}
182 |   Content
183 | {% elsif variable == 'Goodbye' %}
184 |   Content
185 | {% elsif variable == 'Good night' %}
186 |   Content
187 | {% else %}
188 |   Content
189 | {% endif %}
190 | ```
191 | 
192 | #### Do
193 | ```html
194 | {% case variable %}
195 |   {% when 'Hello' %}
196 |     Content
197 |   {% when 'Goodbye' %}
198 |     Content
199 |   {% when 'Good night '%}
200 |     Content
201 |   {% else %}
202 |     Content
203 | {% endcase %}
204 | ```
205 | 
206 | * Do not use `{% if %}` for more than two conditions, use `{% case %}` instead
207 | * `{% case %}` can only be used when exactly matching a condition, you can't use it to test if something `contains`, use `{% if %}` for this purpose
208 | 
209 | ### [Inline `{% if %}` statements](#inline--if--statements)
210 | 
211 | #### Don't
212 | ```html
213 | <div class="row {% if section.settings.width == 'full' or section.settings.display == 'full' %}row--full-width{% endif %} {% if is_hidden %}is-hidden{% endif %}"></div>
214 | ```
215 | 
216 | #### Do
217 | ```html
218 | {% if section.settings.width == 'full' or section.settings.display == 'full' %}
219 |   {% assign row_class = 'row--full-width' %}
220 | {% endif %}
221 | 
222 | <div
223 |   class="
224 |     row
225 |     {{ row_class }}
226 |     {% if is_hidden %}is-hidden{% endif %}
227 |   "
228 | >
229 |   <!-- Content -->
230 | </div>
231 | ```
232 | 
233 | * Do not put long `{% if %}` tags inline, assign them separately
234 | * If the `{% if %}` tag is short you can put it inline
235 | * Only include the space inside the `{% if %}` tag if it's on a single line, otherwise there is no need to include a space
236 | 
237 | [ꜛ Back to TOC](#table-of-contents)
238 | 
239 | ## [DRY (Don't Repeat Yourself)](#dry-dont-repeat-yourself)
240 | 
241 | ### Don't
242 | ```html
243 | <!-- A custom page slider so four slides have been hard-coded in section settings -->
244 | <!-- This means we can't use {% for block in section.blocks %} -->
245 | <div class="slide slide--1">
246 |   <div
247 |     class="slide__background"
248 |     style="background-image: url({{ block.settings.slide_1_image | img_url: '2000x' }});"
249 |   ></div>
250 | 
251 |   <div class="slide__text">
252 |     <h2 class="slide__title">{{ block.settings.slide_1_text }}</h2>
253 |     <p class="slide__copy">{{ block.settings.slide_1_text }}</p>
254 | 
255 |     <div class="slide__buttons">
256 |       <a class="slide__button" href="{{ block.settings.slide_1_button_1_url }}">
257 |         {{ block.settings.slide_1_button_1_text }}
258 |       </a>
259 | 
260 |       <a class="slide__button" href="{{ block.settings.slide_1_button_2_url }}">
261 |         {{ block.settings.slide_1_button_2_text }}
262 |       </a>
263 |     </div>
264 |   </div>
265 | </div>
266 | 
267 | <!-- All of the code is repeat for each hard-coded slide instance -->
268 | <div class="slide slide--2">...</div>
269 | <div class="slide slide--3">...</div>
270 | <div class="slide slide--4">...</div>
271 | ```
272 | 
273 | ### Do
274 | ```html
275 | {% for i in (1..4) %}
276 |   {% assign slide_image = 'slide_#_image' | replace: '#', i %}
277 |   {% assign slide_heading = 'slide_#_heading' | replace: '#', i %}
278 |   {% assign slide_text = 'slide_#_text' | replace: '#', i %}
279 | 
280 |   <div class="slide slide--{{ i }}">
281 |     <div
282 |       class="slide__background"
283 |       style="background-image: url({{ block.settings[slide_image] | img_url: '2000x' }});"
284 |     ></div>
285 | 
286 |     <div class="slide__text">
287 |       <h2 class="slide__heading">{{ block.settings[slide_heading] }}</h2>
288 | 
289 |       <p class="slide__copy">
290 |         {{ block.settings[slide_text] }}
291 |       </p>
292 | 
293 |       <div class="slide__buttons">
294 |         {% for j in (1..2) %}
295 |           {% assign slide_button_url = 'slide_#_button_%_url' |
296 |             replace: '#', i |
297 |             replace: '%', j
298 |           %}
299 | 
300 |           {% assign slide_button_text = 'slide_#_button_%_text' |
301 |             replace: '#', i |
302 |             replace: '%', j
303 |           %}
304 | 
305 |           <a class="slide__button" href="{{ block.settings[slide_button_url]}}">
306 |             {{ block.settings[slide_button_text] }}
307 |           </a>
308 |         {% endfor %}
309 |       </div>
310 |     </div>
311 |   </div>
312 | {% endfor %}
313 | ```
314 | 
315 | * Use `{% for i in (1..#) %}` in combination with `{% assign %}` and replace to remove repetitive code
316 | * Use the iteration to set variables which are then used to call the block's settings
317 | * Use Liquid's built in tags to avoid repeating code
318 | 
319 | [ꜛ Back to TOC](#table-of-contents)
320 | 
321 | ## Formatting
322 | 
323 | * [`{% render %}`](#-render-)
324 | * [Characters](#characters)
325 | * [Indenting](#indenting)
326 | * [Spacing & line character limits](#spacing--line-character-limits)
327 | 
328 | ### [`{% render %}`](#-render-)
329 | 
330 | > 🗒 **Note:** `{% include %}` tags have been deprecated by Shopify and replaced with the `{% render %}` tag. [For full details visit this page](https://help.shopify.com/en/themes/liquid/tags/theme-tags#render).
331 | 
332 | #### Don't
333 | ```html
334 | {% include 'icon-misc', icon: 'search', colour: 'red' %}
335 | {% render 'social-sharing' with share_title: product.title, share_permalink: product.url, share_image: product.featured_image %}
336 | ```
337 | 
338 | #### Do
339 | ```html
340 | {% render 'icon-misc' with icon: 'search', colour: 'red' %}
341 | 
342 | {% render 'social-sharing' with
343 |   share_image: product.featured_image,
344 |   share_permalink: product.url,
345 |   share_title: product.title,
346 | %}
347 | ```
348 | 
349 | * When setting variables on your `{% render %}` always use `with` instead of starting with a comma
350 | * After the first variable declaration you must use a comma `,`
351 | * If there are more than two variables and it goes over 80 characters then break it into a multi-line tag
352 | * Sort the variables alphabetically and end each line with a comma `,`
353 | 
354 | ### [Characters](#characters)
355 | 
356 | #### Don't
357 | ```html
358 | {% assign variable = "It's time for fun" %}
359 | ```
360 | 
361 | #### Do
362 | ```html
363 | {% assign variable = 'It\'s time for fun' %}
364 | ```
365 | 
366 | * Use apostrophes `'` in Liquid objects, tags, and filters, not quotations `"`
367 | * Escape apostrophes if they appear inside the string
368 | 
369 | ### [Indenting](#indenting)
370 | 
371 | #### Don't
372 | ```html
373 | {% if variable %}
374 | <h1>{{ product.title }}</h1>
375 | {% endif %}
376 | ```
377 | 
378 | #### Do
379 | ```html
380 | {% if variable %}
381 |   <h1>{{ product.title }}</h1>
382 | {% endif %}
383 | ```
384 | 
385 | * Treat opening Liquid tags the same as HTML elements; indent two spaces inside
386 | 
387 | ### [Spacing & line character limits](#spacing--line-character-limits)
388 | 
389 | #### Don't
390 | ```html
391 | {% if template contains 'search' or template contains 'account' or template contains 'customer' or template contains 'cart' %}<meta name="robots" content="noindex, nofollow">{% endif %}
392 | {% assign sanitized_var = string|downcase|split: '/'|last|remove:'<p>'|remove:'</p>'|money_with_currency %}
393 | {%if variable%}<h1 class="product__title">{{ product.title }}</h1>
394 |   <div class="product__price product__price--large money subtitle-1">{{ product.price | money }}</div>{% else %}<h2 class="product__title">{{ product.title }}</h2>{%endif%}
395 | ```
396 | 
397 | #### Do
398 | ```html
399 | {% if
400 |   template contains 'search' or
401 |   template contains 'account' or
402 |   template contains 'customer' or
403 |   template contains 'cart'
404 | %}
405 |   <meta content="noindex, nofollow" name="robots">
406 | {% endif %}
407 | 
408 | {% assign sanitized_variable = string |
409 |   downcase |
410 |   split: '/' |
411 |   last |
412 |   remove:'<p>' |
413 |   remove:'</p>' %} |
414 |   money_with_currency
415 | %}
416 | 
417 | {% if variable %}
418 |   <h1 class="product__title">{{ product.title }}</h1>
419 | 
420 |   <div
421 |     class="
422 |       product__price
423 |       product__price--large
424 |       money
425 |       subtitle-1
426 |     "
427 |   >
428 |     {{ product.price | money }}
429 |   </div>
430 | 
431 | {% else %}
432 |   <h2 class="product__title">{{ product.title }}</h2>
433 | {% endif %}
434 | ```
435 | 
436 | * Add spaces inside each object and tag
437 | * Add spaces around filters
438 | * Separate blocks of Liquid code with a newline
439 | * Opening `{% if %}` tags should be on separate lines
440 | * `{% if %}` tags with more than two filters and exceeding 80 characters should be split onto multiple lines
441 | * If the contents of an `{% if %}` tag spans more than two lines add a newline before any following `{% elsif %}` or `{% else %}` tags
442 | * `{% assign %}` tags with more than two filters and exceeding 80 characters should be broken up over multiple lines and indented
443 | * Once you are writing something over multiple lines, each line should only have one attribute or value on it
444 | * For details on HTML spacing see the [HTML](../html/README.md) rule for [Spacing & line character limit](../html/README.md#spacing--line-character-limits)
445 | 
446 | [ꜛ Back to TOC](#table-of-contents)
447 | 
448 | ## [Language strings](#language-strings)
449 | 
450 | ### Don't
451 | ```html
452 | <div class="product-card">
453 |   <h2 class="product-card__title">{{ product.title }}</h2>
454 | 
455 |   <span class="product-card__stock">
456 |     {% if product.available %}
457 |       In stock
458 |     {% else %}
459 |       Out of stock
460 |     {% endif %}
461 |   </span>
462 | </div>
463 | ```
464 | 
465 | ### Do
466 | ```html
467 | <div class="product-card">
468 |   <h2 class="product-card__title">{{ product.title }}</h2>
469 | 
470 |   <span class="product-card__stock">
471 |     {% if product.available %}
472 |       {{ 'products.product.in_stock' | t }}
473 |     {% else %}
474 |       {{ 'products.product.out_of_stock' | t }}
475 |     {% endif %}
476 |   </span>
477 | </div>
478 | ```
479 | 
480 | * Never hard-code text in your template files
481 | * Always use Shopify's [translation filter](https://help.shopify.com/en/themes/development/theme-store-requirements/internationalizing/translation-filter)
482 | * Most of our clients are multi-lingual so it is expected that they will be able to translate their store without requiring additional development
483 | 
484 | [ꜛ Back to TOC](#table-of-contents)
485 | 
486 | ## Naming
487 | 
488 | 1. [Section template naming](#section-template-naming)
489 | 1. [Snippet naming](#Snippet-naming)
490 | 1. [Tag naming](#tag-naming)
491 | 
492 | ### [Section template naming](#section-template-naming)
493 | 
494 | ```html
495 | template-[section].liquid
496 | ```
497 | 
498 | * If a section replaces the template's content it should be prefixed with `template-`
499 | * E.g. `template-product.liquid` or `template-collection.liquid`
500 | 
501 | ### [Snippet naming](#snippet-naming)
502 | 
503 | ```html
504 | icon-[snippet].liquid
505 | ```
506 | 
507 | * Snippets used to contain inline SVGs should be prefixed with `icon-`
508 | * E.g. `icon-payment.liquid`
509 | 
510 | ```html
511 | section-[snippet].liquid
512 | ```
513 | 
514 | * Snippets that contain a section's content should be prefixed with `section-`
515 | * E.g. `section-hero.liquid` or `section-featured-collection.liquid`
516 | 
517 | ### [Tag naming](#tag-naming)
518 | 
519 | ```html
520 | tag_name
521 | tag_name: [value]
522 | tag_name: [value1]_[value2] (etc.)
523 | ```
524 | 
525 | * Use the naming convention `tag_name: [value]` for admin tags (products, orders, customers) with a value and `tag_name` for tags without a value
526 | * In most cases `[value]` should be in lowercase to make comparisons easier. However in instances where the value is outputted on the front-end in a specific case (e.g. Title Case) make sure this is clear in the tech spec
527 | * If you need to store separate values in the same tag then separate them using `_`  such as `type_modal: [Model]_[Year]` (this isn't snake_case)
528 | * Do not use boolean values (e.g. `has_addon: true`) as simply having the tag in the first place is enough to know that it is `true` (e.g. `has_addon`)
529 | * If the tag is to be used in a search string (and therefore needs to be handlelised) then use the naming convention `tag_name--[value]`, this allows the value to be kebab-cased (e.g. `build_date--2019-07-03`)
530 | * Never put formatted money into the tag (e.g. `monthly_cost: £10`) as tags do not support all the formatting standards required by international stores (e.g. `monthly_cost: €12,34` will not be allowed because the comma ends the tag), instead use `monthly_cost: 1234` and format the cost using Liquid or JavaScript
531 | 
532 | [ꜛ Back to TOC](#table-of-contents)
533 | 
534 | ## Schema settings
535 | 
536 | * [`default` & `label`](#default-&-label)
537 | * [Formatting & order](#formatting-&-order)
538 | * [`type`](#type)
539 | 
540 | ### [`default` & `label`](#default-label)
541 | ```json
542 | {
543 |   "type": "text",
544 |   "id": "storeId",
545 |   "label": "Store ID (enter a unique store ID)",
546 | }
547 | ```
548 | 
549 | #### Do
550 | ```json
551 | {
552 |   "type": "text",
553 |   "id": "store_id",
554 |   "label": "Store ID",
555 |   "default": "dev_store",
556 |   "info": "Enter a unique store ID using a snake case naming convention. e.g: gb_store"
557 | }
558 | ```
559 | 
560 | * Don't try to fit everything into `label`, use `info` for more details
561 | * Add a default value where possible, this makes deployment easier
562 | 
563 | ### [Formatting & order](#formatting-&-order)
564 | 
565 | #### Don't
566 | ```json
567 | {
568 |   "id": "storeId",
569 |   "label": "Store ID (enter a unique store ID)",
570 |   "type": "text"
571 | }
572 | ```
573 | 
574 | #### Do
575 | ```json
576 | {
577 |   "type": "text",
578 |   "id": "store_id",
579 |   "label": "Store ID",
580 |   "default": "dev_store",
581 |   "info": "Enter a unique store ID using a snake case naming convention. e.g: gb_store"
582 | }
583 | ```
584 | 
585 | * Use the prescribed order, any other key value pairs should be added below in alphabetical order
586 | * Use snake case for `id`
587 | * Use sentence case for `label` and `info`
588 | 
589 | ### [`Type`](#type)
590 | 
591 | Specific rules for certain settings of `type`:
592 | * `range` – Use for fixed number choices (such as font size, height, duration etc.)
593 | * `richtext` – If you are changing `text` or `textarea` to `richtext` (or vice versa) you will need to delete any existing settings data as it will throw an error
594 | * `select` – Use for fixed text choices (not for numbers)
595 | * `textarea` – Do not use for raw HTML, use `html` for this
596 | * `url` – Only use for all choices, use one of the limited selections if you are only expecting a certain output (`collection`, `product`, `blog`, `page`, and `article`), do not use for video, use `video_url` for this
597 | 
598 | [ꜛ Back to TOC](#table-of-contents)
599 | 
600 | ## Snippets
601 | 
602 | * [Section snippets](#section-snippets)
603 | * [Snippets general](#snippets-general)
604 | 
605 | ### [Section snippets](#section-snippets)
606 | 
607 | * Place the content for a section inside a snippet (see [snippet naming](#snippet-naming) for advice on naming)
608 | * This allows us to use a section anywhere as we can place the snippet inside a `{% case %}` block setup
609 | 
610 | #### Example
611 | 
612 | ##### Section
613 | ```html
614 | {% comment %}
615 | ----------------------------------------------------------------------------
616 |   Section: Featured text
617 |   – Large text banner.
618 | ----------------------------------------------------------------------------
619 | {% endcomment %}
620 | <section
621 |   class="featured-text-section"
622 |   data-section-id="{{ section.id }}"
623 |   data-section-type="featured-text"
624 | >
625 |   {% render 'section-featured-text' with object: section %}
626 | </section>
627 | 
628 | {% schema %}
629 |   {
630 |     "name": "Featured Text",
631 |     <!-- Section settings -->
632 |   }
633 | {% endschema %}
634 | ```
635 | 
636 | ##### Snippet
637 | ```html
638 | <!-- Code removed for brevity -->
639 | <div class="featured-text">
640 |   {% if object.settings.title != '' %}
641 |     <p class="featured-text__copy body-1">
642 |       {{ object.settings.title }}
643 |     </p>
644 |   {% endif %}
645 | </div>
646 | ```
647 | 
648 | * With this setup you would then be able to add `{% render 'section-featured-text' with object: block %}` on a page other than the homepage
649 | * With `{% render %}` you would need to include all the parameters that the snippet requires
650 | 
651 | ### [Snippets general](#snippets-general)
652 | 
653 | * Use Liquid snippets to keep files small and manageable
654 | * In the same way a block gets its own SCSS and JS file, consider splitting it into its own snippet
655 | * Snippets are especially useful for repeating content
656 | 
657 | [ꜛ Back to TOC](#table-of-contents)
658 | 
659 | ## [Split characters](#split-characters)
660 | 
661 | Split characters are used to effectively provide multiple description fields on the product page. It is useful when you need to output long form content in multiple locations.
662 | 
663 | ### Example
664 | ```html
665 | {% if product.description != '' %}
666 |   {% assign full_description = product.description |
667 |     remove: '<meta charset="utf-8">' |
668 |     remove: '<meta charset="utf-8" />' |
669 |     remove: '<span>' |
670 |     remove: '</span>' |
671 |     remove: '<p>&nbsp;</p>' |
672 |     remove: '<p> </p>' |
673 |     remove: '<p></p>'
674 |   %}
675 | 
676 |   {% if full_description contains '---DESCRIPTION---' %}
677 |     {% assign description = full_description |
678 |       split: '<p>---DESCRIPTION---</p>' |
679 |       last |
680 |       split: '<p>---' |
681 |       first
682 |     %}
683 |   {% endif %}
684 | 
685 |   {% if full_description contains '---SIZE GUIDE---' %}
686 |     {% assign size_guide = full_description |
687 |       split: '<p>---SIZE GUIDE---</p>' |
688 |       last |
689 |       split: '<p>---' |
690 |       first
691 |     %}
692 |   {% endif %}
693 | {% endif %}
694 | 
695 | {% if description %}
696 |   <div class="product__description rte">
697 |     {{ description }}
698 |   </div>
699 | {% endif %}
700 | 
701 | {% if size_guide %}
702 |   <div class="product__size-guide rte">
703 |     {{ size_guide }}
704 |   </div>
705 | {% endif %}
706 | ```
707 | 
708 | * Use split characters in the format `---[NAME]---` where `[NAME]` is the identifying name of the split content
709 | * `[NAME]` can have spaces, e.g. `---COMPATIBLE INFO---`
710 | * Assign the split description to variables at the top of the file then output the variable as and when you need it
711 | * Use split characters over metafields as they don't require any special apps to access and content can be automatically imported using apps like Excelify
712 | * Shopify tends to add extra HTML so in the example this has been stripped off, including empty line returns
713 | 
714 | [ꜛ Back to TOC](#table-of-contents)
715 | 
716 | ## Variables
717 | 
718 | 1. [Assigning](#variable-assigning)
719 | 1. [Grouping](#variable-grouping)
720 | 1. [Naming](#variable-naming)
721 | 
722 | ### [Variable assigning](#variable-assigning)
723 | 
724 | #### Don't
725 | ```html
726 | {% for product in collection.products %}
727 |   {% if product.tags contains 'has_shipping' %}
728 |     {% assign has_shipping_tag = true %}
729 |   {% endif %}
730 | {% endif %}
731 | ```
732 | 
733 | #### Do
734 | ```html
735 | {% for product in collection.products %}
736 |   {% assign has_shipping_tag = false %}
737 | 
738 |   {% if product.tags contains 'has_shipping' %}
739 |     {% assign has_shipping_tag = true %}
740 |   {% endif %}
741 | {% endif %}
742 | ```
743 | 
744 | * Assign the default state of a variable before you first use it
745 | * This avoids false positives in `{% for %}` loops as it resets the variable at the start of each item
746 | * In the Don't example above once one product had the tag the variable is set to `true`, but nothing resets it meaning all products after it will have the variable set to `true`
747 | 
748 | ### [Variable grouping](#variable-grouping)
749 | 
750 | #### Don't
751 | ```html
752 | {% assign variable_a = 'Hello world' %}
753 | 
754 | <h1>{{ product.title }}</h1>
755 | <div>{{ product.description }}</div>
756 | {% assign variable_b = 'Hello world' %}
757 | {% assign variable_c = 'Hello world' %}
758 | 
759 | {% for variant in product.variants %}
760 |   <h2>{{ variant.title }}</h2>
761 |   {% assign variable_d = variant.title %}
762 | {% endfor %}
763 | 
764 | {% assign variable_e = 'Hello world' %}
765 | {% for product in recommendations.products %}
766 |   <span>{{ product.title | link_to: product.url }}</span>
767 | {% endfor %}
768 | ```
769 | 
770 | #### Do
771 | ```html
772 | {% assign variable_a = 'Hello world' %}
773 | {% assign variable_b = 'Hello world' %}
774 | {% assign variable_c = 'Hello world' %}
775 | {% assign variable_e = 'Hello world' %}
776 | 
777 | <h1>{{ product.title }}</h1>
778 | <div>{{ product.description }}</div>
779 | 
780 | {% for variant in product.variants %}
781 |   <h2>{{ variant.title }}</h2>
782 |   {% assign variable_d = variant.title %}
783 | {% endfor %}
784 | 
785 | {% for product in recommendations.products %}
786 |   <span>{{ product.title | link_to: product.url }}</span>
787 | {% endfor %}
788 | ```
789 | 
790 | * Group all variables which are not set inside specific `{% forloop %}` at the top of the file
791 | * If there are lots of variables consider placing them in a variables file, e.g. in the product section you would place them in a _product-variables.liquid_ snippet
792 | 
793 | ### [Variable naming](#variable-naming)
794 | 
795 | #### Don't
796 | ```html
797 | {% assign variableName = 'Hello world' %}
798 | {% capture img-var %}
799 |   This isn't right
800 | {% endcapture %}
801 | ```
802 | 
803 | #### Do
804 | ```html
805 | {% assign variable_string = 'Hello world' %}
806 | {% capture another_string %}
807 |   This is correct
808 | {% endcapture %}
809 | ```
810 | 
811 | * Use snake case when naming variables
812 | * Do not use abbreviations or shortened words
813 | * Keep the name easy to understand
814 | 
815 | #### More examples
816 | ```html
817 | {% assign has_shipping_tag = true %}
818 | {% assign is_catalogue_product = false %}
819 | 
820 | {% assign additional_handle_array = 'Item 1,Item 2,Item 3' | split: ',' %}
821 | 
822 | {% assign installation_search_string = '' %}
823 | ```
824 | 
825 | * If a variable is a boolean then name it as a question, 'has the shipping tag' becomes `has_shipping_tag`
826 | * If the variable is an array, then append `_array` to the name
827 | * If it's a string than append `_string`
828 | * This makes it obvious what you're dealing with when you have a lot of variables
829 | 
830 | [ꜛ Back to TOC](#table-of-contents)
831 | 
832 | ## [Whitespace controls](#whitespace-controls)
833 | 
834 | ### Don't
835 | ```html
836 | {%- if variable_name -%}
837 |   {%- assign another_variable = false -%}
838 | {%- endif -%}
839 | ```
840 | 
841 | ### Do
842 | ```html
843 | {% if variable_name %}
844 |   {% assign another_variable = false %}
845 | {% endif %}
846 | ```
847 | 
848 | * Do not use [whitespace control](https://help.shopify.com/en/themes/liquid/basics/whitespace_) on tags
849 | * If you need to trim whitespace from objects then you can use whitespace controls, e.g. `{{- section.settings.body_copy -}}`
850 | 
851 | > **🗒 Note:** Not all apps support whitespace controls.
852 | 
853 | [ꜛ Back to TOC](#table-of-contents)


--------------------------------------------------------------------------------
/frame/vs-code/README.md:
--------------------------------------------------------------------------------
 1 | # VS Code Settings
 2 | 
 3 | The below settings are recommended to help you follow our other guidelines.
 4 | 
 5 | ## Table of contents
 6 | 
 7 | 1. [Extensions](#extensions)
 8 | 1. [Settings](#settings)
 9 | 
10 | ## Extensions
11 | 
12 | These are the minimum extensions we recommend you have installed.
13 | 
14 | These links will open the Visual Studio Marketplace.
15 | 
16 | * [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2)
17 | * [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
18 | * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
19 | * [Import Cost](https://marketplace.visualstudio.com/items?itemName=wix.vscode-import-cost)
20 | * [Liquid Languages Support](https://marketplace.visualstudio.com/items?itemName=neilding.language-liquid)
21 | * [Shopify Liquid Template Snippets](https://marketplace.visualstudio.com/items?itemName=killalau.vscode-liquid-snippets)
22 | * [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)
23 | 
24 | 
25 | [ꜛ Back to TOC](#table-of-contents)
26 | 
27 | ## Settings
28 | 
29 | Useful settings to make your life easier.
30 | 
31 | ### Changing your settings
32 | 
33 | 1. Press `cmd` + `,` to open the settings dialog in VS Code
34 | 1. Click the arrow pointing to the page icon in top right
35 | 1. Paste settings below into the JSON format file this has opened
36 | 
37 | ### Table of contents
38 | 
39 | * [Character limit](#character-limit)
40 | * [Disable file preview](#disable-file-preview)
41 | * [File associations](#file-associations)
42 | * [Git autofetch](#git-autofetch)
43 | * [Trim trailing whitespace](#trim-trailing-whitespace)
44 | 
45 | ### [Character limit](#character-limit)
46 | 
47 | ```js
48 | "editor.rulers": [
49 |   80
50 | ],
51 | "workbench.colorCustomizations": {
52 |   "editorRuler.foreground": "#ffffff33"
53 | }
54 | ```
55 | 
56 | * Adds a vertical border in your code editor denoting where the 80 character limit is
57 | * The colour is in the hexadecimal colour with an additional alpha value
58 | 
59 | ### [Disable file preview](#disable-file-preview)
60 | 
61 | ```js
62 | "workbench.editor.enablePreviewFromQuickOpen": false
63 | ```
64 | 
65 | * When opening files from `cmd` + `p` file search they won't open in preview mode
66 | * This means that opening another file won't close the previous one
67 | 
68 | ### [File associations](#file-associations)
69 | 
70 | ```js
71 | "files.associations": {
72 |   "*.scss.liquid": "scss",
73 |   "*.js.liquid": "javascript"
74 | }
75 | ```
76 | 
77 | * This tells VS Code to ignore the `.liquid` extension and open the files with the write sort of highlighting enabled
78 | 
79 | ### [Git autofetch](#git-autofetch)
80 | 
81 | ```js
82 | "git.autofetch": true
83 | ```
84 | 
85 | * Autofetches the Git repo every five minutes
86 | 
87 | ### [Trim trailing whitespace](#trim-trailing-whitespace)
88 | 
89 | ```js
90 | "files.trimTrailingWhitespace": true
91 | ```
92 | 
93 | * Trims any trailing whitespace on file save (makes linting happy)
94 | 
95 | [ꜛ Back to TOC](#table-of-contents)
96 | 
97 | [← Back to homepage](../README.md)


--------------------------------------------------------------------------------
/html-vue-template/README.md:
--------------------------------------------------------------------------------
  1 | # HTML & Vue `<template>` Guidelines
  2 | 
  3 | These rules apply to all Liquid, HTML, and Vue `<template>` code.
  4 | 
  5 | See also [Vue's style guide](https://vuejs.org/style-guide/).
  6 | 
  7 | ## Table of contents
  8 | 
  9 | * [Attributes](#attributes)
 10 | * [Characters](#characters)
 11 | * [Commenting](#commenting)
 12 | * [`<div>` or `<span>`](#div-or-span)
 13 | * [Indenting](#indenting)
 14 | * [Spacing & line character limits](#spacing--line-character-limits)
 15 | * [Self-closing element](#self-closing-elements)
 16 | * [Vue render tags](#vue-render-tags)
 17 | 
 18 | [← Back to homepage](../README.md)
 19 | 
 20 | ## Attributes
 21 | 
 22 | * [Attribute casing](#attribute-casing)
 23 | * [Attribute order](#attribute-order)
 24 | 
 25 | ### Attribute casing
 26 | 
 27 | * The general rule is if the attribute is to do with CSS then you use kebab-case for the value
 28 | * If the attribute is for JavaScript then use camelCase in the value
 29 | * kebab-case
 30 |   * `id`
 31 |   * `class`
 32 |   * `for`
 33 | * camelCase
 34 |   * `v-` bind
 35 |   * Vue `@` events
 36 |   * `data-`
 37 |   * `js-` selector values
 38 | 
 39 | ### Attribute order
 40 | 
 41 | #### Don't
 42 | 
 43 | ```html
 44 | {% # Liquid file %}
 45 | <input id="NewsletterModal-Email" class="newsletter-modal__textarea" autocapitalize="off" autocomplete="newsletter-address" autocorrect="off" name="contact[email]" placeholder="{{ 'general.newsletter_form.email_placeholder' | t }}" type="email" value="{{ customer.email }}" aria-labelledby="NewsletterModal-EmailLabel" data-show="true" js-newsletter="email">
 46 | ```
 47 | 
 48 | #### Do
 49 | 
 50 | ```html
 51 | {% # Liquid file %}
 52 | <input
 53 |   id="newsletter-modal-email"
 54 |   class="newsletter-modal__textarea"
 55 |   autocapitalize="off"
 56 |   autocomplete="newsletter-address"
 57 |   autocorrect="off"
 58 |   name="contact[email]"
 59 |   placeholder="{{ 'general.newsletter_form.email_placeholder' | t }}"
 60 |   type="email"
 61 |   value="{{ customer.email }}"
 62 |   aria-labelledby="newsletter-modal-email-label"
 63 |   data-show="true"
 64 |   js-newsletter="email"
 65 | >
 66 | ```
 67 | 
 68 | * When an element has more than one attribute then each attribute should be on its own line
 69 | * Attributes should follow this order:
 70 |   * `is`
 71 |   * `v-for`
 72 |   * `v-if` / `v-else-if` / `v-else`
 73 |   * `v-show`
 74 |   * `v-cloak`
 75 |   * `id`
 76 |   * `ref`
 77 |   * `key`
 78 |   * `v-model`
 79 |   * `class`
 80 |   * { native }
 81 |   * `aria-`
 82 |   * `data-`
 83 |   * `js-`
 84 |   * `@event`
 85 |   * `v-html` / `v-text`
 86 | * { native } covers everything else, items within { native } should be in alphabetical order
 87 | * This makes it easier for managing merges in Git
 88 | * Make sure you trim trailing spaces after each line
 89 | * See also [spacing & line character limits](#spacing--line-character-limits)
 90 | 
 91 | > Be sure to follow the formatting; the trailing `>` should be on a newline with the attributes indented in two spaces.
 92 | 
 93 | ## Characters
 94 | 
 95 | ### Don't
 96 | 
 97 | ```html
 98 | <div class='foo'></div>
 99 | ```
100 | 
101 | ### Do
102 | 
103 | ```html
104 | <div class="foo"></div>
105 | ```
106 | 
107 | * Use double quotations `"` in HTML elements, not apostrophes/single quotations `'`
108 | * Note that you should use single quotations in Liquid tags and filters
109 | 
110 | [ꜛ Back to TOC](#table-of-contents)
111 | 
112 | ## `<div>` or `<span>`
113 | 
114 | `<div>` and `<span>` are often used interchangeably but there are specific use cases for each:
115 | 
116 | * If the content is going to be displayed inline, use `<span>`
117 | * If you want the element to display block, on its own line, use `<div>`
118 | * If you're using CSS to change its `display` property, consider using the other
119 | 
120 | [ꜛ Back to TOC](#table-of-contents)
121 | 
122 | ## Indenting
123 | 
124 | ### Don't
125 | 
126 | ```html
127 | <p class="body-1">
128 | {{ product.description }}
129 | </p>
130 | ```
131 | 
132 | ### Do
133 | 
134 | ```html
135 | <p class="body-1">
136 |   {{ product.description }}
137 | </p>
138 | ```
139 | 
140 | * Indent two spaces inside each opening HTML element
141 | 
142 | [ꜛ Back to TOC](#table-of-contents)
143 | 
144 | ## Spacing & line character limits
145 | 
146 | ### Don't
147 | 
148 | ```html
149 | {% # Liquid file %}
150 | <div id="Product" class="product" data-id="{{ product.id }}" js-product="container">
151 |   <h1 class="product__title">{{ product.title }}</h1>
152 |   <h2 class="product__subtitle">{{ product.type }}</h2>
153 |   <button class="product__button product-button"><span class="product-button__icon">{% render 'icon-misc' with icon: 'plus' %}</span><span class="product-button__text">{{ 'products.product.add_to_cart' | t }}</span></button>
154 |   <div class="product__content product-content">
155 |     <p class="product-content__description">{{ product.description }}</p>
156 |     <p class="product-content__shipping">{{ pages['shipping'].content | strip_html }}</p>
157 |   </div>
158 |   <div class="footer"><div class="footer__inner"><span class="footer__copy">{{ 'footer.copyright' | t }}</span><span class="footer__name">{{ shop.name }}</span><img src="{{ settings.logo | img_url: '300x' }}" alt="{{ settings.logo.alt }}"></div></div>
159 | </div>
160 | ```
161 | 
162 | ### Do
163 | 
164 | ```html
165 | {% # Liquid file %}
166 | <div
167 |   id="Product"
168 |   class="product"
169 |   data-id="{{ product.id }}"
170 |   js-product="container"
171 | >
172 |   <h1 class="product__title">{{ product.title }}</h1>
173 |   <h2 class="product__subtitle">{{ product.type }}</h2>
174 | 
175 |   <button class="product__button product-button">
176 |     <span class="product-button__icon">
177 |       {% render 'icon-misc' with icon: 'plus' %}
178 |     </span>
179 | 
180 |     <span class="product-button__text">
181 |       {{ 'products.product.add_to_cart' | t }}
182 |     </span>
183 |   </button>
184 | 
185 |   <div class="product__content product-content">
186 |     <p class="product-content__description">
187 |       {{ product.description }}
188 |     </p>
189 | 
190 |     <div class="product-content__shipping">
191 |       {{ pages['shipping'].content }}
192 |     </div>
193 |   </div>
194 | 
195 |   <div class="footer">
196 |     <div class="footer__inner">
197 |       <span class="footer__copy">{{ 'footer.copyright' | t }}</span>
198 |       <span class="footer__name">{{ shop.name }}</span>
199 | 
200 |       <img
201 |         alt="{{ settings.logo.alt }}"
202 |         src="{{ settings.logo | img_url: '300x' }}"
203 |       >
204 |     </div>
205 |   </div>
206 | </div>
207 | ```
208 | 
209 | * Use common sense spacing to improve the readability of your code
210 | * [Block-level elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements) should open onto a new line and indent
211 | * [Inline-level elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#Elements) should be written on a single line
212 | * Single line elements should be grouped together by type
213 | * Multi-line elements should have a newline between them
214 | * This guideline includes empty block-level elements, e.g. the following is correct:
215 | 
216 | ```html
217 | {% # Liquid file %}
218 | <div
219 |   class="article__image"
220 |   data-bgset="{% render 'responsive-bg-image' with image: article.image %}"
221 |   js-article="image"
222 | ></div>
223 | ```
224 | 
225 | * Once you are writing something over multiple lines, each line should only have one attribute or value on it
226 | * If an attribute's value exceeds 80 characters then it too should be split in the following format:
227 | 
228 | ```html
229 | {% # Liquid file %}
230 | <div
231 |   class="
232 |     class-1
233 |     class-2
234 |     class-3
235 |     class-4
236 |   "
237 |   data-handle="{{ product.handle }}"
238 |   js-product="content"
239 | >
240 |   {% # Content %}
241 | </div>
242 | ```
243 | 
244 | ### Exceptions
245 | 
246 | * Short block-level elements like `<h1>`, `<li>` or `<title>` can be displayed on a single line unless they're greater than 80 characters long
247 | * Inline-level elements greater than 80 characters long should follow multi-line rules
248 | 
249 | [ꜛ Back to TOC](#table-of-contents)
250 | 
251 | ## Self-closing elements
252 | 
253 | ### Don't
254 | 
255 | ```html
256 | {% # Liquid file %}
257 | <component-handle />
258 | 
259 | <img
260 |   alt=""
261 |   src="{{ 'image.png' | file_url: '200x' }}"
262 | />
263 | 
264 | <input
265 |   class="foo"
266 |   placeholder="Content"
267 |   type="text"
268 | />
269 | ```
270 | 
271 | ### Do
272 | 
273 | ```html
274 | {% # Liquid file %}
275 | <component-handle></component-handle>
276 | 
277 | <img
278 |   alt=""
279 |   src="{{ 'image.png' | file_url: '200x' }}"
280 | >
281 | 
282 | <input
283 |   class="foo"
284 |   placeholder="Content"
285 |   type="text"
286 | >
287 | ```
288 | 
289 | * Vue custom elements in Liquid files should not use a self-closing tag as this is invalid and causes errors
290 | * The `/` in self-closing tags is obsolete in most HTML elements, do not use it
291 | 
292 | ### Exceptions
293 | 
294 | * Inside a Vue `<template>` tag you should use self-closing tags for elements which don't normally self-close:
295 | 
296 | ```html
297 | <!-- .vue file -->
298 | <h1
299 |   class="main-product__title"
300 |   v-html="product.title"
301 | />
302 | ```
303 | 
304 | [ꜛ Back to TOC](#table-of-contents)
305 | 
306 | ## Vue render tags
307 | 
308 | ### Don't
309 | 
310 | ```html
311 | <!-- .vue file -->
312 | <h1 class="main-product__title">
313 |   {{ product.title }}
314 | </h1>
315 | ```
316 | 
317 | ### Do
318 | 
319 | ```html
320 | <!-- .vue file -->
321 | <h1
322 |   class="main-product__title"
323 |   v-html="product.title"
324 | />
325 | ```
326 | 
327 | * Use `v-html` or `v-text` to render content in an element instead of using the template render tags
328 | 
329 | [ꜛ Back to TOC](#table-of-contents)
330 | 


--------------------------------------------------------------------------------
/javascript-vue-sfc/README.md:
--------------------------------------------------------------------------------
  1 | # JavaScript & Vue SFC
  2 | 
  3 | Our guidelines are predominately based on [@shopify/eslint-plugin](https://github.com/Shopify/web-configs/tree/main/packages/eslint-plugin) with exceptions.
  4 | 
  5 | See also [Vue's style guide](https://vuejs.org/style-guide/).
  6 | 
  7 | When saving `eslint --fix` should run and automatically fix most issues.
  8 | 
  9 | ## Table of contents
 10 | 
 11 | * [Arrays](#arrays)
 12 | * [Comments](#comments)
 13 | * [If conditions](#if-conditions)
 14 | * [Indents](#indents)
 15 | * [Newlines](#newlines)
 16 | * [Objects](#objects)
 17 | * [Order](#order)
 18 | * [Passing parameters](#passing-parameters)
 19 | * [Semi-colons](#semi-colons)
 20 | * [Variables](#variables)
 21 | * [Whitespace](#whitespace)
 22 | 
 23 | [← Back to homepage](../README.md)
 24 | 
 25 | ## Arrays
 26 | 
 27 | ### Don't
 28 | 
 29 | ```js
 30 | const foo = [
 31 |   'bar'
 32 | ]
 33 | 
 34 | const bar = ['foo',
 35 |   'bar'
 36 | ]
 37 | ```
 38 | 
 39 | ### Do
 40 | 
 41 | ```js
 42 | const foo = ['bar']
 43 | 
 44 | const bar = [
 45 |   'foo',
 46 |   'bar',
 47 | ]
 48 | ```
 49 | 
 50 | * Single item arrays should be on a single line with no spaces inside the opening and closing tags
 51 | * Multiple item arrays should have each item on a newline with a trailing comma
 52 | 
 53 | [ꜛ Back to TOC](#table-of-contents)
 54 | 
 55 | ## Comments
 56 | 
 57 | * [Comments general](#comments-general)
 58 | * [Long form](#long-form-comments)
 59 | * [JSDoc](#jsdoc-comments)
 60 | * [Short form](short-form-comments)
 61 | 
 62 | ### General comments
 63 | 
 64 | * Add a newline after comments, except those starting with `eslint` or `webpack`
 65 | * Comments should begin with a capital letter
 66 | 
 67 | ### Long form comments
 68 | 
 69 | ```js
 70 | /**
 71 |  * Folder: Title
 72 |  * -----------------------------------------------------------------------------
 73 |  * Description.
 74 |  *
 75 |  */
 76 | ```
 77 | 
 78 | * Use the long form comment for intro comments inside the `<script>` tag in Vue files and at the start of JS files
 79 | 
 80 | ### JSDoc comments
 81 | 
 82 | ```js
 83 | /**
 84 |  * [Comment].
 85 |  * @param {String} variable - Variable description.
 86 |  * @returns {String}
 87 |  */
 88 | ```
 89 | 
 90 | * Use the JSDoc comment before every function explaining what it does, its expected variables, and what it returns
 91 | * Wrap the variable in square brackets to denote that it's optional, e.g. `[variable]`
 92 | * See [JSDoc documentation](https://jsdoc.app/) for details
 93 | 
 94 | ### Short form comments
 95 | 
 96 | ```js
 97 | /**
 98 |  * Comment.
 99 |  */
100 | ```
101 | 
102 | * Use the short form comment for general comments
103 | 
104 | [ꜛ Back to TOC](#table-of-contents)
105 | 
106 | ## If conditions
107 | 
108 | * [Early return](#early-return)
109 | * [Ternary operator](#ternary-operator)
110 | 
111 | ### Early return
112 | 
113 | #### Don't
114 | 
115 | ```js
116 | if (condition) {
117 |   runFunctionA()
118 | } else {
119 |   runFunctionB()
120 | }
121 | ```
122 | 
123 | #### Do
124 | 
125 | ```js
126 | if (condition) {
127 |   runFunctionA()
128 |   return
129 | }
130 | 
131 | runFunctionB()
132 | ```
133 | 
134 | * Use an early return instead of `if ... else` where possible to make the amount of code the browser has to run shorter
135 | * Where both parts of the condition lead to the same outcome you should continue using `if ... else`, e.g.
136 | 
137 | ```js
138 | let foo = ''
139 | 
140 | if (condition) {
141 |   foo += 'Foo'
142 | } else {
143 |   foo += 'Bar'
144 | }
145 | 
146 | foo += 'Baz'
147 | 
148 | return foo
149 | ```
150 | 
151 | ### Ternary operator
152 | 
153 | #### Don't
154 | 
155 | ```js
156 | let foo = 'Baz'
157 | 
158 | if (condition) {
159 |   foo = 'Bar'
160 | }
161 | 
162 | const bar = condition ? 'When the ternary would exceed 80 characters then split onto newlines' : 'Foo'
163 | ```
164 | 
165 | #### Do
166 | 
167 | ```js
168 | const foo = condition ? 'Bar' : 'Baz'
169 | 
170 | const bar = condition
171 |   ? 'When the ternary would exceed 80 characters then split onto newlines'
172 |   : 'Foo'
173 | ```
174 | 
175 | * When assigning a variable it's preferrable to use a ternary operator, e.g.
176 | * Split the ternary operator onto newlines when it exceeds 80 characters
177 | 
178 | [ꜛ Back to TOC](#table-of-contents)
179 | 
180 | ## Newlines
181 | 
182 | ### Don't
183 | 
184 | ```js
185 | const foo = 'Bar'
186 | const bar = [
187 |   true,
188 |   false,
189 |   true,
190 | ]
191 | bar.forEach((item) => {
192 |   if (item) return
193 |   runFunction(item)
194 | })
195 | if (condition) { foo = 'Baz' }
196 | ```
197 | 
198 | ## Do
199 | 
200 | ```js
201 | const foo = 'Bar'
202 | 
203 | const bar = [
204 |   true,
205 |   false,
206 |   true,
207 | ]
208 | 
209 | bar.forEach((item) => {
210 |   if (item) {
211 |     return
212 |   }
213 | 
214 |   runFunction(item)
215 | })
216 | 
217 | if (condition) {
218 |   foo = 'Baz'
219 | }
220 | ```
221 | 
222 | * Newlines are free, use them to break up blocks of code
223 | * Multi-line objects should have newlines before and after them
224 | * Do not use single line if conditions
225 | 
226 | [ꜛ Back to TOC](#table-of-contents)
227 | 
228 | ## Objects
229 | 
230 | ### Don't
231 | 
232 | ```js
233 | const foo = {
234 |   'bar': true
235 | }
236 | 
237 | const bar = {'foo': true, 'bar-baz': false}
238 | ```
239 | 
240 | ### Do
241 | 
242 | ```js
243 | const foo = { bar: true }
244 | 
245 | const bar = {
246 |   foo: true,
247 |   'bar-baz': false,
248 | }
249 | ```
250 | 
251 | * Each property in an object should be on a newline if there are multiple properties
252 | * For single property objects there should be a space after the opening brace and before the closing brace
253 | * Single word keys should not use an apostrophes/single quotations (`'`)
254 | * All properties in a multi-line object must always have a trailing comma
255 | 
256 | [ꜛ Back to TOC](#table-of-contents)
257 | 
258 | ## Order
259 | 
260 | * [Attributes](#attributes)
261 | * [Vue SFC order](#vue-sfc-order)
262 | 
263 | ### Attributes
264 | 
265 | * As per [Vue's style guide](https://vuejs.org/style-guide/rules-recommended.html#component-instance-options-order) your Vue `<script>` export should follow this order:
266 |   * `name`
267 |   * `components`
268 |   * `props`
269 |   * `emits`
270 |   * `setup`
271 |   * `data`
272 |   * `computed`
273 |   * `watch`
274 |   * Lifecycle events in the order they're called
275 |   * `methods`
276 | 
277 | ### Vue SFC order
278 | 
279 | * Vue SFC files should be in the following order:
280 |   * `<template>`
281 |   * `<script>`
282 |   * `<style>`
283 | 
284 | [ꜛ Back to TOC](#table-of-contents)
285 | 
286 | ## Indents
287 | 
288 | * [Indents general](#indents-general)
289 | * [Vue SFC indentation](#vue-sfc-indentation)
290 | 
291 | ### Indents general
292 | 
293 | * When saving your file `eslint --fix` is automatically run, if there are items which need to break onto multiple lines (such as arrays) then `eslint` will do this for you, however the indenting may be incorrect
294 | * Apply common sense when saving a file which `eslint` then fixes, if the indenting doesn't look right it probably isn't, `eslint` doesn't lint indenting correctly at all times
295 | 
296 | ### Vue SFC indentation
297 | 
298 | #### Don't
299 | 
300 | ```html
301 | <template>
302 | <div class="example">
303 |   <!-- Code -->
304 | </div>
305 | </template>
306 | 
307 | <script>
308 |   export default {
309 |     name: 'Example',
310 |   }
311 | </script>
312 | 
313 | <style lang="scss">
314 |   @import './example';
315 | </style>
316 | ```
317 | 
318 | #### Do
319 | 
320 | ```html
321 | <template>
322 |   <div class="Example">
323 |     <!-- Code -->
324 |   </div>
325 | </template>
326 | 
327 | <script>
328 | export default {
329 |   name: 'Example',
330 | }
331 | </script>
332 | 
333 | <style lang="scss">
334 | @import './example';
335 | </style>
336 | ```
337 | 
338 | * Only indent the contents of the `<template>` tag
339 | * `<script>` and `<style>` tags should not be indented
340 | * This gives more character length to write your JS in
341 | 
342 | [ꜛ Back to TOC](#table-of-contents)
343 | 
344 | ## Passing parameters
345 | 
346 | ### Don't
347 | 
348 | ```js
349 | array.forEach(item => {
350 |   // Code
351 | })
352 | ```
353 | 
354 | ### Do
355 | 
356 | ```js
357 | array.forEach((item) => {
358 |   // Code
359 | })
360 | ```
361 | 
362 | * Wrap the passed parameters in brackets `()`
363 | 
364 | [ꜛ Back to TOC](#table-of-contents)
365 | 
366 | ## Semi-colons
367 | 
368 | ### Don't
369 | 
370 | ```js
371 | const foo = 'Bar';
372 | ```
373 | 
374 | ### Do
375 | 
376 | ```js
377 | const foo = 'Bar'
378 | ```
379 | 
380 | * Do not use semi-colons (`;`) unless not doing so would cause an ASI error
381 | * E.g. the below needs a semi-colon on the first line otherwise when minified it would break:
382 | 
383 | ```js
384 | const array = [];
385 | 
386 | ['foo', 'bar'].forEach((value) => {
387 |   array.push(value))
388 | }
389 | ```
390 | 
391 | [ꜛ Back to TOC](#table-of-contents)
392 | 
393 | ## Variables
394 | 
395 | ### Don't
396 | 
397 | ```js
398 | var foo = true
399 | 
400 | let bar = [
401 |   'One',
402 |   'Two',
403 |   'Three',
404 | ]
405 | 
406 | const baz = 'String'
407 | baz += ', extra string'
408 | ```
409 | 
410 | ### Do
411 | 
412 | ```js
413 | const foo = true
414 | 
415 | const bar = [
416 |   'One',
417 |   'Two',
418 |   'Three',
419 | ]
420 | 
421 | let baz = 'String'
422 | baz += ', extra string'
423 | ```
424 | 
425 | * Do not use `var`, use `let` or `const` as the situation dictates
426 | * Use `const` for variables which are _never_ reassigned
427 | * Use `let` for variables which are reassigned
428 | 
429 | [ꜛ Back to TOC](#table-of-contents)
430 | 
431 | ## Whitespace
432 | 
433 | ### Don't
434 | 
435 | ```js
436 | const foo='Bar'
437 | 
438 | array.forEach((item)=>{
439 |   // Code
440 | })
441 | 
442 | for(const item of array){
443 |   // Code
444 | }
445 | 
446 | if(condition==='foo'){
447 |   // Code
448 | }else{
449 |   // Code
450 | }
451 | ```
452 | 
453 | ### Do
454 | 
455 | ```js
456 | const foo = 'Bar'
457 | 
458 | array.forEach((item) => {
459 |   // Code
460 | })
461 | 
462 | for (const item of array) {
463 |   // Code
464 | }
465 | 
466 | if (condition === 'foo') {
467 |   // Code
468 | } else {
469 |   // Code
470 | }
471 | ```
472 | 
473 | * Whitespace is free, use it
474 | * It makes the code more readable
475 | 
476 | [ꜛ Back to TOC](#table-of-contents)
477 | 


--------------------------------------------------------------------------------
/liquid/README.md:
--------------------------------------------------------------------------------
  1 | # Liquid Guidelines
  2 | 
  3 | For details on how to pass Liquid variables to Vue props, see [Canvas documentation](https://www.notion.so/wemakewebsites/Passing-Liquid-to-Vue-9367b24ce4ae447bbfc6471794f01b7a).
  4 | 
  5 | ## Table of contents
  6 | 
  7 | * [`{% liquid %}` tag](#-liquid--tag)
  8 | * [Commenting](#commenting)
  9 | * [Conditional statements](#conditional-statements)
 10 | * [DRY (Don't Repeat Yourself)](#dry-dont-repeat-yourself)
 11 | * [Formatting](#formatting)
 12 | * [Language strings](#language-strings)
 13 | * [Naming](#naming)
 14 | * [Schema & section settings](#schema--section-settings)
 15 | * [Snippets](#snippets)
 16 | * [Split characters](#split-characters)
 17 | * [Variables](#variables)
 18 | * [Whitespace controls](#whitespace-controls)
 19 | 
 20 | [← Back to homepage](../README.md)
 21 | 
 22 | ## `{% liquid %}` tag
 23 | 
 24 | #### Don't
 25 | 
 26 | ```html
 27 | {% assign variable_a = 'Hello world' %}
 28 | {% assign variable_b = 'Hello world' %}
 29 | {% assign variable_c = 'Hello world' %}
 30 | {% render 'snippet' %}
 31 | ```
 32 | 
 33 | #### Do
 34 | 
 35 | ```html
 36 | {%- liquid
 37 |   assign variable_a = 'Hello world'
 38 |   assign variable_b = 'Hello world'
 39 |   assign variable_c = 'Hello world'
 40 |   assign variable_e = 'Hello world'
 41 |   render 'snippet'
 42 | -%}
 43 | ```
 44 | 
 45 | * When using multiple Liquid tags replace with a single `{%- liquid -%}` tag
 46 | * Use whitespace controls to remove whitespace from around the statement when rendered
 47 | * See [Shopify documentation](https://shopify.dev/api/liquid/tags/theme-tags#liquid) for more details
 48 | 
 49 | ## Commenting
 50 | 
 51 | * [Inline](#inline)
 52 | * [Long](#long)
 53 | * [Introductory](#introductory)
 54 | 
 55 | ### Inline
 56 | 
 57 | #### Don't
 58 | 
 59 | ```html
 60 | <!-- Only display description if tag is present -->
 61 | {% if has_tag %}
 62 |   <div class="foo">{{ product.description }}</div>
 63 | {% endif %}
 64 | ```
 65 | 
 66 | #### Do
 67 | 
 68 | ```html
 69 | {% # Only display description if tag is present %}
 70 | {% if has_tag %}
 71 |   <div class="foo">
 72 |     {{ product.description }}
 73 |   </div>
 74 | {% endif %}
 75 | ```
 76 | 
 77 | * Use the `{% # [Comment] %}` tag for inline comments, not HTML comments
 78 | * HTML comments are included in the compiled HTML
 79 | * For `.js.liquid` or `.scss.liquid` file use the language appropriate comment format
 80 | 
 81 | ### Long
 82 | 
 83 | #### Do
 84 | 
 85 | ```html
 86 | {% comment %}
 87 | ------------------------------------------------------------------------------
 88 |   Lorem ipsume dolor sit amet:
 89 |   - Feature 1.
 90 |   - Feature 2.
 91 |   - Feature 3.
 92 | ------------------------------------------------------------------------------
 93 | {% endcomment %}
 94 | ```
 95 | 
 96 | * For longer comments (or lists) you the `{% comment %}{% endcomment %}` tags
 97 | 
 98 | ### Introductory
 99 | 
100 | #### Do
101 | 
102 | ```html
103 | {% comment %}
104 | ------------------------------------------------------------------------------
105 |   Section: Featured link
106 |   - Used to display up to 2 images with text overlays with links.
107 | ------------------------------------------------------------------------------
108 | {% endcomment %}
109 | ```
110 | 
111 | * Include an introductory comment at the start of each file
112 | * Describe what folder it's in, the file's name, and list any special features or conditions
113 | * If it's a snippet then provide a list of parameters that it supports using the [JSDoc format](https://jsdoc.app/)
114 | ```html
115 | {% comment %}
116 | -----------------------------------------------------------------------------
117 |   Snippet: Line item (line-item)
118 | 
119 |   @param {String} [block_class] - Block level class to apply to all elements.
120 |   @param {String} [class] - Additional classes.
121 |   @param {Number} [index] - Index for line item, used for animation delay.
122 |   @param {Boolean|Object} [item] - Line item in cart response or order.
123 |   @param {Boolean} [loading_animation] - Force the display of the loading state.
124 | -----------------------------------------------------------------------------
125 | {% endcomment %}
126 | ```
127 | 
128 | [ꜛ Back to TOC](#table-of-contents)
129 | 
130 | ## Conditional statements
131 | 
132 | * [Conditional settings](#conditional-settings)
133 | * [Conditional spacing](#conditional-spacing)
134 | * [`{% if %}` or `{% case %}`](#-if--or--case-)
135 | * [Inline `{% if %}` statements](#inline--if--statements)
136 | 
137 | ### Conditional settings
138 | 
139 | #### Don't
140 | 
141 | ```html
142 | {% for block in section.blocks %}
143 |   <div class="block">
144 |     <img src="{{ block.settings.image | img_url: '2000x' }}" alt="{{ block.settings.image.alt }}">
145 | 
146 |     <h2 class="block__title">{{ block.settings.title }}</h2>
147 |     <div class="block__text rte">{{ block.settings.text }}</div>
148 | 
149 |     <a class="block__button" href="{{ block.settings.button_url }}">
150 |       {{ block.settings.button_text }}
151 |     </a>
152 |   </div>
153 | {% endfor %}
154 | ```
155 | 
156 | #### Do
157 | 
158 | ```html
159 | {% for block in section.blocks %}
160 |   <div class="block">
161 |     {% if block.settings.image != blank %}
162 |       <img
163 |         alt="{{ block.settings.image.alt }}"
164 |         src="{{ block.settings.image | img_url: '2000x' }}"
165 |       >
166 |     {% endif %}
167 | 
168 |     {% if block.settings.title != blank %}
169 |       <h2 class="block__title">{{ block.settings.title }}</h2>
170 |     {% endif %}
171 | 
172 |     {% if block.settings.text != blank %}
173 |       <div class="block__text rte">
174 |         {{ block.settings.text }}
175 |       </div>
176 |     {% endif %}
177 | 
178 |     {% if block.settings.button url != blank and block.settings.button_text != blank %}
179 |       <a class="block__button" href="{{ block.settings.button_url }}">
180 |         {{ block.settings.button_text }}
181 |       </a>
182 |     {% endif %}
183 |   </div>
184 | {% endfor %}
185 | ```
186 | 
187 | * In areas where the client can customise the content do not assume they will fill in every setting
188 | * Wrap each setting in a `{% if %}` to hide it if no content is entered
189 | * Use `!= blank` rather than `{% if condition %}` or `!= ''` as it is more reliable
190 | * See [setting states](./setting-states.md) for a full breakdown of what each setting returns when empty or cleared
191 | * Don't only develop and test based on what's in the design; the client will expect it to work regardless of which settings are missing
192 | 
193 | ### Conditional spacing
194 | 
195 | #### Don't
196 | 
197 | ```html
198 | {% if condition %}
199 |   {% # Multiple lines of code %}
200 |   {% # Multiple lines of code %}
201 |   {% # Multiple lines of code %}
202 | {% else %}
203 |   {% # Multiple lines of code %}
204 |   {% # Multiple lines of code %}
205 |   {% # Multiple lines of code %}
206 | {% endif %}
207 | ```
208 | 
209 | #### Do
210 | 
211 | ```html
212 | {% if condition %}
213 |   {% # Multiple lines of code %}
214 |   {% # Multiple lines of code %}
215 |   {% # Multiple lines of code %}
216 | 
217 | {% else %}
218 |   {% # Multiple lines of code %}
219 |   {% # Multiple lines of code %}
220 |   {% # Multiple lines of code %}
221 | {% endif %}
222 | ```
223 | 
224 | * When an `{% if %}` tag spans multiple lines add a newline before the `{% else %}` tag
225 | * This helps visually separate the code and make it easier to scan
226 | 
227 | ### `{% if %}` or `{% case %}`
228 | 
229 | #### Don't
230 | 
231 | ```html
232 | {% if variable == 'Hello' %}
233 |   {% # Code %}
234 | {% elsif variable == 'Goodbye' %}
235 |   {% # Code %}
236 | {% elsif variable == 'Good night' %}
237 |   {% # Code %}
238 | {% else %}
239 |   {% # Code %}
240 | {% endif %}
241 | ```
242 | 
243 | #### Do
244 | 
245 | ```html
246 | {%- liquid
247 |   case variable
248 |     when 'Hello'
249 |       {% # Code %}
250 |     when 'Goodbye'
251 |       {% # Code %}
252 |     when 'Good night'
253 |       {% # Code %}
254 |     else
255 |       {% # Code %}
256 |   endcase
257 | -%}
258 | ```
259 | 
260 | * Do not use `{% if %}` for more than two conditions, use `{% case %}` instead
261 | * `{% case %}` can only be used when exactly matching a condition, you can't use it to test if something `contains`, use `{% if %}` for this purpose
262 | 
263 | ### Inline `{% if %}` statements
264 | 
265 | #### Don't
266 | 
267 | ```html
268 | <div class="row {% if section.settings.width == 'full' or section.settings.display == 'full' %}row--full-width{% endif %} {% if is_hidden %}is-hidden{% endif %}"></div>
269 | ```
270 | 
271 | #### Do
272 | 
273 | ```html
274 | {%- liquid
275 |   if section.settings.width == 'full' or section.settings.display == 'full'
276 |     assign row_class = 'row--full-width'
277 |   endif
278 | -%}
279 | 
280 | <div
281 |   class="
282 |     row
283 |     {{ row_class }}
284 |     {% if is_hidden %}is-hidden{% endif %}
285 |   "
286 | >
287 |   <!-- Content -->
288 | </div>
289 | ```
290 | 
291 | * Do not put long `{% if %}` tags inline, assign them separately
292 | * If the `{% if %}` tag is short you can put it inline
293 | * Only include the space inside the `{% if %}` tag if it's on a single line, otherwise there is no need to include a space
294 | 
295 | [ꜛ Back to TOC](#table-of-contents)
296 | 
297 | ## DRY (Don't Repeat Yourself)
298 | 
299 | ### Don't
300 | 
301 | ```html
302 | {% # A custom page slider so four slides have been hard-coded in section settings %}
303 | {% # This means we can't use {% for block in section.blocks %}
304 | <div class="slide slide--1">
305 |   <div
306 |     class="slide__background"
307 |     style="background-image: url({{ block.settings.slide_1_image | img_url: '2000x' }});"
308 |   ></div>
309 | 
310 |   <div class="slide__text">
311 |     <h2 class="slide__title">{{ block.settings.slide_1_text }}</h2>
312 |     <p class="slide__copy">{{ block.settings.slide_1_text }}</p>
313 | 
314 |     <div class="slide__buttons">
315 |       <a class="slide__button" href="{{ block.settings.slide_1_button_1_url }}">
316 |         {{ block.settings.slide_1_button_1_text }}
317 |       </a>
318 | 
319 |       <a class="slide__button" href="{{ block.settings.slide_1_button_2_url }}">
320 |         {{ block.settings.slide_1_button_2_text }}
321 |       </a>
322 |     </div>
323 |   </div>
324 | </div>
325 | 
326 | {% # All of the code is repeat for each hard-coded slide instance %}
327 | <div class="slide slide--2">...</div>
328 | <div class="slide slide--3">...</div>
329 | <div class="slide slide--4">...</div>
330 | ```
331 | 
332 | ### Do
333 | 
334 | ```html
335 | {% for i in (1..4) %}
336 |   {%- liquid
337 |     assign slide_image = 'slide_#_image' | replace: '#', i
338 |     assign slide_heading = 'slide_#_heading' | replace: '#', i
339 |     assign slide_text = 'slide_#_text' | replace: '#', i
340 |   -%}
341 | 
342 |   <div class="slide slide--{{ i }}">
343 |     <div
344 |       class="slide__background"
345 |       style="background-image: url({{ block.settings[slide_image] | image_url: width: 2000 }});"
346 |     ></div>
347 | 
348 |     <div class="slide__text">
349 |       <h2 class="slide__heading">{{ block.settings[slide_heading] }}</h2>
350 | 
351 |       <p class="slide__copy">
352 |         {{ block.settings[slide_text] }}
353 |       </p>
354 | 
355 |       <div class="slide__buttons">
356 |         {% for j in (1..2) %}
357 |           {%- liquid
358 |             assign slide_button_url = 'slide_#_button_%_url' | replace: '#', i | replace: '%', j
359 |             assign slide_button_text = 'slide_#_button_%_text' | replace: '#', i | replace: '%', j
360 |           -%}
361 | 
362 |           <a
363 |             class="slide__button"
364 |             href="{{ block.settings[slide_button_url] }}"
365 |           >
366 |             {{ block.settings[slide_button_text] }}
367 |           </a>
368 |         {% endfor %}
369 |       </div>
370 |     </div>
371 |   </div>
372 | {% endfor %}
373 | ```
374 | 
375 | * Use an numerical forloop (e.g. `{% for i in (1..#) %}`) in combination with `{% assign %}` to replace repetitive code
376 | * Use the iteration to set variables which are then used to call the block's settings
377 | * Use Liquid's built in tags to avoid repeating code
378 | 
379 | [ꜛ Back to TOC](#table-of-contents)
380 | 
381 | ## Formatting
382 | 
383 | * [`{% render %}`](#-render-)
384 | * [Characters](#characters)
385 | * [Indenting](#indenting)
386 | * [Spacing & line character limits](#spacing--line-character-limits)
387 | 
388 | ### `{% render %}`
389 | 
390 | #### Don't
391 | 
392 | ```html
393 | {% include 'icon-misc', icon: 'search', colour: 'red' %}
394 | {% render 'social-sharing' with share_title: product.title, share_permalink: product.url, share_image: product.featured_image %}
395 | ```
396 | 
397 | #### Do
398 | 
399 | ```html
400 | {% render 'icon-misc' with icon: 'search', colour: 'red' %}
401 | 
402 | {% render 'social-sharing' with
403 |   share_image: product.featured_image,
404 |   share_permalink: product.url,
405 |   share_title: product.title,
406 | %}
407 | ```
408 | 
409 | * When setting variables on your `{% render %}` always use `with` instead of starting with a comma
410 | * After the first variable declaration you must use a comma `,`
411 | * If there are more than two variables and it goes over 80 characters then break it into a multi-line tag
412 | * Sort the variables alphabetically and end each line with a comma `,`
413 | 
414 | > `{% include %}` tags have been deprecated by Shopify and replaced with the `{% render %}` tag. [For full details visit this page](https://help.shopify.com/en/themes/liquid/tags/theme-tags#render).
415 | 
416 | ### Characters
417 | 
418 | #### Don't
419 | 
420 | ```html
421 | {% assign variable = "It's time for fun" %}
422 | ```
423 | 
424 | #### Do
425 | 
426 | ```html
427 | {% assign variable = 'It\'s time for fun' %}
428 | ```
429 | 
430 | * Use apostrophes `'` in Liquid objects, tags, and filters, not quotations `"`
431 | * Escape apostrophes if they appear inside the string
432 | 
433 | ### Indenting
434 | 
435 | #### Don't
436 | 
437 | ```html
438 | {% if variable %}
439 | <h1>{{ product.title }}</h1>
440 | {% endif %}
441 | ```
442 | 
443 | #### Do
444 | 
445 | ```html
446 | {% if variable %}
447 |   <h1>{{ product.title }}</h1>
448 | {% endif %}
449 | ```
450 | 
451 | * Treat opening Liquid tags the same as HTML elements; indent two spaces inside
452 | 
453 | ### Spacing & line character limits
454 | 
455 | #### Don't
456 | 
457 | ```html
458 | {% if template contains 'search' or template contains 'account' or template contains 'customer' or template contains 'cart' %}<meta name="robots" content="noindex, nofollow">{% endif %}
459 | {% assign sanitized_var = string|downcase|split: '/'|last|remove:'<p>'|remove:'</p>'|money_with_currency %}
460 | {%if variable%}<h1 class="product__title">{{ product.title }}</h1>
461 |   <div class="product__price product__price--large money subtitle-1">{{ product.price | money }}</div>{% else %}<h2 class="product__title">{{ product.title }}</h2>{%endif%}
462 | ```
463 | 
464 | #### Do
465 | 
466 | ```html
467 | {% if
468 |   template contains 'search' or
469 |   template contains 'account' or
470 |   template contains 'customer' or
471 |   template contains 'cart'
472 | %}
473 |   <meta content="noindex, nofollow" name="robots">
474 | {% endif %}
475 | 
476 | {%- liquid
477 |   assign sanitized_variable = string | downcase | split: '/' | last | remove: '<p>'
478 |   assign sanitized_variable = sanitized_variable | remove: '</p>' | money_with_currency
479 | -%}
480 | 
481 | {% if variable %}
482 |   <h1 class="product__title">{{ product.title }}</h1>
483 | 
484 |   <div
485 |     class="
486 |       product__price
487 |       product__price--large
488 |       money
489 |       subtitle-1
490 |     "
491 |   >
492 |     {{ product.price | money }}
493 |   </div>
494 | 
495 | {% else %}
496 |   <h2 class="product__title">{{ product.title }}</h2>
497 | {% endif %}
498 | ```
499 | 
500 | * Add spaces inside each object and tag
501 | * Add spaces around filters
502 | * Separate blocks of Liquid code with a newline
503 | * Opening `{% if %}` tags should be on separate lines
504 | * `{% if %}` tags with more than two filters and exceeding 80 characters should be split onto multiple lines
505 | * If the contents of an `{% if %}` condition branch spans more than two lines add a newline before any following `{% elsif %}` or `{% else %}` tags
506 | * Once you are writing something over multiple lines, each line should only have one attribute or value on it
507 | * For details on HTML spacing see the [HTML](../html/README.md) rule for [Spacing & line character limit](../html/README.md#spacing--line-character-limits)
508 | 
509 | #### Liquid filters
510 | 
511 | * Previously we recommended placing Liquid filters on newlines when there are more than two and the Liquid exceeded 80 characters
512 | * This approach is not compatible with the [`{% liquid %}` tag](#-liquid--tag)
513 | * We now recommended keeping filters on the same line and the `{% liquid %}` tag is our preferred approach
514 | * However if there are a large number of filters being used on an `{% assign %}` then consider splitting the Liquid onto multiple lines like in the example above
515 | 
516 | [ꜛ Back to TOC](#table-of-contents)
517 | 
518 | ## Language strings
519 | 
520 | ### Don't
521 | 
522 | ```html
523 | <div class="product-card">
524 |   <h2 class="product-card__title">{{ product.title }}</h2>
525 | 
526 |   <span class="product-card__stock">
527 |     {% if product.available %}
528 |       In stock
529 |     {% else %}
530 |       Out of stock
531 |     {% endif %}
532 |   </span>
533 | </div>
534 | ```
535 | 
536 | ### Do
537 | 
538 | ```html
539 | <div class="product-card">
540 |   <h2 class="product-card__title">{{ product.title }}</h2>
541 | 
542 |   <span class="product-card__stock">
543 |     {% if product.available %}
544 |       {{ 'products.product.in_stock' | t }}
545 |     {% else %}
546 |       {{ 'products.product.out_of_stock' | t }}
547 |     {% endif %}
548 |   </span>
549 | </div>
550 | ```
551 | 
552 | * Never hard-code text in your template files
553 | * Always use Shopify's [translation filter](https://help.shopify.com/en/themes/development/theme-store-requirements/internationalizing/translation-filter)
554 | * Most of our clients are multi-language so it is expected that they will be able to translate their store without requiring additional development
555 | 
556 | [ꜛ Back to TOC](#table-of-contents)
557 | 
558 | ## Naming
559 | 
560 | * [Section template naming](#section-template-naming)
561 | * [Snippet naming](#Snippet-naming)
562 | * [Tag naming](#tag-naming)
563 | 
564 | ### Section template naming
565 | 
566 | ```html
567 | main-[section].liquid
568 | ```
569 | 
570 | * If a section replaces the template's content it should be prefixed with `main-` and moved into the _main_ folder in _sections_ (if it isn't an async component)
571 | * E.g. `main-product.liquid` or `main-collection.liquid`
572 | 
573 | ### Snippet naming
574 | 
575 | ```html
576 | section-[snippet].liquid
577 | ```
578 | 
579 | * Snippets that contain a section's content should be prefixed with `section-`
580 | * E.g. `section-hero.liquid` or `section-featured-collection.liquid`
581 | 
582 | ### Tag naming
583 | 
584 | ```html
585 | tag_name
586 | tag_name: [value]
587 | tag_name: [value1]_[value2] (etc.)
588 | ```
589 | 
590 | * Use the naming convention `tag_name: [value]` for tags in Shopify admin (products, orders, customers) with a value and `tag_name` for tags without a value
591 | * In most cases `[value]` should be in lowercase to make comparisons easier
592 | * However in instances where the value is outputted on the front-end in a specific case (e.g. Title Case) make sure this is clear in the tech spec
593 | * If you need to store separate values in the same tag then separate them using `_`  such as `type_modal: [Model]_[Year]` (this isn't snake_case)
594 | * Do not use boolean values (e.g. `has_addon: true`) as simply having the tag in the first place is enough to know that it is `true` (e.g. `has_addon`)
595 | * If the tag is to be used in a search string (and therefore needs to be handlelised) then use the naming convention `tag_name--[value]`, this allows the value to be kebab-cased (e.g. `build_date--2019-07-03`)
596 | * Never put formatted money into the tag (e.g. `monthly_cost: £12.34`) as tags do not support all the formatting standards required by international stores (e.g. `monthly_cost: €12,34` will not be allowed because the comma ends the tag), instead provide the value in cents (e.g. `monthly_cost: 1234`) and format the cost using Liquid or JavaScript
597 | 
598 | [ꜛ Back to TOC](#table-of-contents)
599 | 
600 | ## Schema & section settings
601 | 
602 | * [`default` & `label`](#default-&-label)
603 | * [Formatting & order](#formatting-&-order)
604 | * [`type`](#type)
605 | 
606 | ### `default` & `label`
607 | ```json
608 | {
609 |   "type": "text",
610 |   "id": "storeId",
611 |   "label": "Store ID (enter a unique store ID)",
612 | }
613 | ```
614 | 
615 | #### Do
616 | 
617 | ```json
618 | {
619 |   "type": "text",
620 |   "id": "store_id",
621 |   "label": "Store ID",
622 |   "info": "Enter a unique store ID using a snake case naming convention. e.g: gb_store",
623 |   "default": "dev_store"
624 | }
625 | ```
626 | 
627 | * Don't try to fit everything into `label`, use `info` for more details
628 | * Add a default value where possible, this makes deployment easier
629 | 
630 | ### Formatting & order
631 | 
632 | #### Don't
633 | 
634 | ```json
635 | {
636 |   "id": "storeId",
637 |   "label": "Store ID (enter a unique store ID)",
638 |   "type": "text"
639 | }
640 | ```
641 | 
642 | #### Do
643 | 
644 | ```json
645 | {
646 |   "type": "text",
647 |   "id": "store_id",
648 |   "label": "Store ID",
649 |   "info": "Enter a unique store ID using a snake case naming convention. e.g: gb_store",
650 |   "default": "dev_store"
651 | }
652 | ```
653 | 
654 | * Use the prescribed order:
655 |   * `type`
656 |   * `id`
657 |   * `label`
658 |   * `info`
659 |   * `accept` (video_url)
660 |   * `limit` (collection_list, product_list)
661 |   * `min` (range)
662 |   * `max` (range)
663 |   * `step` (range)
664 |   * `unit` (range)
665 |   * `options` (radio, select)
666 |   * `placeholder` (number, text, textarea, html, video_url)
667 |   * `default`
668 | * Use snake_case for `id`
669 | * Use sentence case for `label` and `info`
670 | 
671 | ### `type`
672 | 
673 | Specific rules for certain settings of `type`:
674 | * `range` – Use for fixed number choices (such as font size, height, duration etc.)
675 | * `richtext` – If you are changing `text` or `textarea` to `richtext` (or vice versa) you will need to delete any existing settings data as it will throw an error
676 | * `select` – Use for fixed text choices (not for numbers)
677 | * `textarea` – Do not use as it doesn't support dynamic content sources
678 | * `url` – Only use for all choices, use one of the limited selections if you are only expecting a certain output (`collection`, `product`, `blog`, `page`, and `article`), do not use for video, use `video_url` for this
679 | 
680 | [ꜛ Back to TOC](#table-of-contents)
681 | 
682 | ## Snippets
683 | 
684 | * Use Liquid snippets to keep files small and manageable
685 | * In the same way a block gets its own SCSS and JS file, consider splitting it into its own snippet
686 | * Snippets are especially useful for repetitive content
687 | 
688 | [ꜛ Back to TOC](#table-of-contents)
689 | 
690 | ## Split characters
691 | 
692 | Split characters are used to effectively provide multiple description fields on the product page. It is useful when you need to output long form content in multiple locations.
693 | 
694 | > Using Shopify native metafields is now the preferred approach.
695 | 
696 | ### Example
697 | ```html
698 | {%- liquid
699 |   if product.description != ''
700 |     assign full_description = product.description | remove: '<meta charset="utf-8">' | remove: '<meta charset="utf-8" />'
701 |     assign full_description = full_description | remove: '<span>' | remove: '</span>'
702 |     assign full_description = full_description | remove: '<p>&nbsp;</p>' | remove: '<p> </p>' | remove: '<p></p>'
703 | 
704 |     if full_description contains '---DESCRIPTION---'
705 |       assign description = full_description | split: '<p>---DESCRIPTION---</p>' | last | split: '<p>---' | first
706 |     endif
707 | 
708 |     if full_description contains '---SIZE GUIDE---'
709 |       assign size_guide = full_description | split: '<p>---SIZE GUIDE---</p>' | last | split: '<p>---' | first
710 |     endif
711 |   endif
712 | -%}
713 | 
714 | {% if description %}
715 |   <div class="product__description rte">
716 |     {{ description }}
717 |   </div>
718 | {% endif %}
719 | 
720 | {% if size_guide %}
721 |   <div class="product__size-guide rte">
722 |     {{ size_guide }}
723 |   </div>
724 | {% endif %}
725 | ```
726 | 
727 | * Use split characters in the format `---[NAME]---` where `[NAME]` is the identifying name of the split content
728 | * `[NAME]` can have spaces, e.g. `---COMPATIBLE INFO---`
729 | * Assign the split description to variables at the top of the file then output the variable as and when you need it
730 | * Shopify tends to add extra HTML so in the example this has been stripped off, including empty line returns
731 | 
732 | [ꜛ Back to TOC](#table-of-contents)
733 | 
734 | ## Variables
735 | 
736 | * [Assigning](#variable-assigning)
737 | * [Grouping](#variable-grouping)
738 | * [Naming](#variable-naming)
739 | 
740 | ### Variable assigning
741 | 
742 | #### Don't
743 | 
744 | ```html
745 | {% for product in collection.products %}
746 |   {% if product.tags contains 'has_shipping' %}
747 |     {% assign has_shipping_tag = true %}
748 |   {% endif %}
749 | {% endif %}
750 | ```
751 | 
752 | #### Do
753 | 
754 | ```html
755 | {%- liquid
756 |   for product in collection.products
757 |     assign has_shipping_tag = false
758 | 
759 |     if product.tags contains 'has_shipping'
760 |       assign has_shipping_tag = true
761 |     endif
762 |   endif
763 | -%}
764 | ```
765 | 
766 | * Assign the default state of a variable before you first use it
767 | * This avoids false positives in `{% for %}` loops as it resets the variable at the start of each item
768 | * In the Don't example above once the variable is set to `true` it will never be reset meaning all products after the variable changes will be `true` even if they don't meet the conditions
769 | 
770 | ### Variable grouping
771 | 
772 | #### Don't
773 | 
774 | ```html
775 | {% assign variable_a = 'Hello world' %}
776 | 
777 | <h1>{{ product.title }}</h1>
778 | <div>{{ product.description }}</div>
779 | {% assign variable_b = 'Hello world' %}
780 | {% assign variable_c = 'Hello world' %}
781 | 
782 | {% for variant in product.variants %}
783 |   {% assign variable_d = variant.title %}
784 |   <h2>{{ variable_d }}</h2>
785 | {% endfor %}
786 | 
787 | {% assign variable_e = 'Hello world' %}
788 | {% for product in recommendations.products %}
789 |   <span>{{ product.title | link_to: product.url }}</span>
790 | {% endfor %}
791 | ```
792 | 
793 | #### Do
794 | 
795 | ```html
796 | {%- liquid
797 |   assign variable_a = 'Hello world'
798 |   assign variable_b = 'Hello world'
799 |   assign variable_c = 'Hello world'
800 |   assign variable_e = 'Hello world'
801 | -%}
802 | 
803 | <h1>{{ product.title }}</h1>
804 | <div>{{ product.description }}</div>
805 | 
806 | {% for variant in product.variants %}
807 |   {% assign variable_d = variant.title %}
808 |   <h2>{{ variable_d }}</h2>
809 | {% endfor %}
810 | 
811 | {% for product in recommendations.products %}
812 |   <span>{{ product.title | link_to: product.url }}</span>
813 | {% endfor %}
814 | ```
815 | 
816 | * Group all variables which are not set inside a specific `{% for %}` tag at the top of the file
817 | 
818 | ### Variable naming
819 | 
820 | #### Don't
821 | 
822 | ```html
823 | {% assign variableName = 'Hello world' %}
824 | 
825 | {% capture img-var %}
826 |   This isn't right
827 | {% endcapture %}
828 | ```
829 | 
830 | #### Do
831 | 
832 | ```html
833 | {% assign variable_string = 'Hello world' %}
834 | 
835 | {% capture another_string %}
836 |   This is correct
837 | {% endcapture %}
838 | ```
839 | 
840 | * Use snake case when naming variables
841 | * Do not use abbreviations or shortened words
842 | * Keep the name easy to understand
843 | 
844 | #### More examples
845 | 
846 | ```html
847 | {%- liquid
848 |   assign has_shipping_tag = true
849 |   assign is_catalogue_product = false
850 | 
851 |   assign additional_handle_array = 'Item 1,Item 2,Item 3' | split: ','
852 | 
853 |   assign installation_search_string = ''
854 | -%}
855 | ```
856 | 
857 | * If a variable is a boolean then name it as a question, 'has the shipping tag' becomes `has_shipping_tag`
858 | * If the variable is an array, then append `_array` to the name
859 | * If it's a string than append `_string`
860 | * This makes it obvious what you're dealing with when you have a lot of variables
861 | 
862 | [ꜛ Back to TOC](#table-of-contents)
863 | 
864 | ## Whitespace controls
865 | 
866 | * Only use whitespace controls when using a `{% liquid %}` tag or providing props to a Vue component
867 | * If you need to trim whitespace from objects then you can use whitespace controls, e.g. `{{- section.settings.body_copy -}}`
868 | 
869 | > Not all apps support whitespace controls.
870 | 
871 | [ꜛ Back to TOC](#table-of-contents)
872 | 


--------------------------------------------------------------------------------
/liquid/setting-states.md:
--------------------------------------------------------------------------------
 1 | # Section & Schema setting states
 2 | 
 3 | The below table details what each setting returns.
 4 | 
 5 | * _Empty_ means the setting has never been set
 6 | * _Cleared_ means it's been set and then cleared
 7 | * Each heading means that the setting `==` the heading, e.g. `number == ''` or `image_picker == blank`
 8 | * Based on the condition being `true` a check is rendered, and a cross if it's `false`
 9 | 
10 | ## Results
11 | 
12 | |**Name**|**Type**|`''`|`false`|`nil`|`empty`|`blank`|
13 | |--- |--- |--- |--- |--- |--- |--- |
14 | |number|empty|❌|❌|✅|❌|✅|
15 | ||cleared|❌|❌|✅|❌|✅|
16 | |radio|empty|❌|❌|❌|❌|❌|
17 | ||cleared|❌|❌|❌|❌|❌|
18 | |range|empty|❌|❌|❌|❌|❌|
19 | ||cleared|❌|❌|❌|❌|❌|
20 | |select|empty|❌|❌|❌|❌|❌|
21 | ||cleared|❌|❌|❌|❌|❌|
22 | |text|empty|✅|❌|❌|✅|✅|
23 | ||cleared|✅|❌|❌|✅|✅|
24 | |textarea|empty|✅|❌|❌|✅|✅|
25 | ||cleared|✅|❌|❌|✅|✅|
26 | |article|empty|✅|❌|✅|✅|✅|
27 | ||cleared|✅|❌|✅|✅|✅|
28 | |blog|empty|✅|❌|✅|✅|✅|
29 | ||cleared|✅|❌|✅|✅|✅|
30 | |collection|empty|✅|❌|✅|✅|✅|
31 | ||cleared|✅|❌|✅|✅|✅|
32 | |collection_list|empty|❌|❌|❌|✅|✅|
33 | ||cleared|❌|❌|❌|✅|✅|
34 | |html|empty|✅|❌|❌|✅|✅|
35 | ||cleared|✅|❌|❌|✅|✅|
36 | |image_picker|empty|❌|❌|✅|❌|✅|
37 | ||cleared|❌|❌|✅|❌|✅|
38 | |link_list|empty|✅|❌|✅|✅|✅|
39 | ||cleared|✅|❌|✅|✅|✅|
40 | |liquid|empty|❌|❌|✅|❌|✅|
41 | ||cleared|❌|❌|✅|❌|✅|
42 | |page|empty|✅|❌|✅|✅|✅|
43 | ||cleared|✅|❌|✅|✅|✅|
44 | |product|empty|✅|❌|✅|✅|✅|
45 | ||cleared|✅|❌|✅|✅|✅|
46 | |product_list|empty|❌|❌|❌|✅|✅|
47 | ||cleared|❌|❌|❌|✅|✅|
48 | |richtext|empty|✅|❌|❌|✅|✅|
49 | ||cleared|✅|❌|❌|✅|✅|
50 | |url|empty|❌|❌|✅|❌|✅|
51 | ||cleared|❌|❌|✅|❌|✅|
52 | |video_url|empty|❌|❌|✅|❌|✅|
53 | ||cleared|❌|❌|✅|❌|✅|
54 | 
55 | ## Notes
56 | 
57 | * Number can't be cleared once set, it defaults to `0`
58 | * Radio, range, and select always have a value
59 | 


--------------------------------------------------------------------------------
/vs-code/README.md:
--------------------------------------------------------------------------------
  1 | # VS Code Settings
  2 | 
  3 | The below settings are recommended to help you follow our other guidelines.
  4 | 
  5 | ## Extensions
  6 | 
  7 | These are the minimum extensions we recommend you have installed.
  8 | 
  9 | Canvas projects can automatically install these extensions in VS Code.
 10 | 
 11 | These links will open the Visual Studio Marketplace.
 12 | 
 13 | * [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
 14 | * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
 15 | * [GraphQL](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)
 16 | * [GraphQL Syntax](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql-syntax)
 17 | * [Highlight Matching Tag](https://marketplace.visualstudio.com/items?itemName=vincaslt.highlight-matching-tag)
 18 | * [Import Cost](https://marketplace.visualstudio.com/items?itemName=wix.vscode-import-cost)
 19 | * [Shopify Liquid](https://marketplace.visualstudio.com/items?itemName=Shopify.theme-check-vscode) (disable Theme check, see below)
 20 | * [stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)
 21 | * [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
 22 | * [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
 23 | 
 24 | We do not recommend the Prettier extension as it's _too_ opinionated.
 25 | 
 26 | ## Settings
 27 | 
 28 | Useful settings to make your life easier.
 29 | 
 30 | Canvas projects can automatically apply these settings in VS Code.
 31 | 
 32 | ### Changing your settings
 33 | 
 34 | 1. Press `cmd` + `,` (`ctrl` + `,` on Windows) to open the settings dialog in VS Code
 35 | 1. Click the arrow pointing to the page icon in top right
 36 | 1. Paste settings below into the JSON format file this has opened
 37 | 
 38 | ### Table of contents
 39 | 
 40 | * [Bracket colourisation](#bracket-colourisation)
 41 | * [Character limit](#character-limit)
 42 | * [Diff whitespace](#diff-whitespace)
 43 | * [Disable file preview](#disable-file-preview)
 44 | * [Disable theme check](#disable-theme-check)
 45 | * [End of line character](#end-of-line-character)
 46 | * [File associations](#file-associations)
 47 | * [Git autofetch](#git-autofetch)
 48 | * [HTML validation](#html-validation)
 49 | * [Lint on save](#lint-on-save)
 50 | * [Tab size](#tab-size)
 51 | * [Trim trailing whitespace](#trim-trailing-whitespace)
 52 | 
 53 | ### Bracket colourisation
 54 | 
 55 | ```json
 56 | "editor.bracketPairColorization.enabled": true
 57 | ```
 58 | 
 59 | * VS Code natively supports bracket colourisation so you no longer need the extension
 60 | 
 61 | ### Character limit
 62 | 
 63 | ```json
 64 | "editor.rulers": [
 65 |   80
 66 | ],
 67 | "workbench.colorCustomizations": {
 68 |   "editorRuler.foreground": "#ffffff33"
 69 | }
 70 | ```
 71 | 
 72 | * Adds a vertical border in your code editor denoting where the 80 character limit is
 73 | * `editorRuler.foreground` sets the colour of the ruler using alpha-hexadecimal values
 74 | 
 75 | ### Diff whitespace
 76 | 
 77 | ```json
 78 | "diffEditor.ignoreTrimWhitespace": false
 79 | ```
 80 | 
 81 | * Don't ignore whitespace in the diff view of VS Code
 82 | * See [trim trailing whitespace](#trim-trailing-whitespace) so you don't have to manually remove trailing whitespace
 83 | 
 84 | ### Disable file preview
 85 | 
 86 | ```json
 87 | "workbench.editor.enablePreviewFromQuickOpen": false
 88 | ```
 89 | 
 90 | * When opening files from `cmd` + `p` (or `ctrl` + `p` on Windows) file search they won't open in preview mode
 91 | * This means that opening another file won't close the previous one
 92 | 
 93 | ### Disable theme check
 94 | 
 95 | ```json
 96 | "shopifyLiquid.disableWindowsWarning": true,
 97 | "shopifyLiquid.formatterDevPreview": false,
 98 | "themeCheck.checkOnChange": false,
 99 | "themeCheck.checkOnOpen": false,
100 | "themeCheck.checkOnSave": false,
101 | "themeCheck.onlySingleFileChecks": true,
102 | "workbench.editor.enablePreviewFromQuickOpen": false
103 | ```
104 | 
105 | * We use the Shopify Liquid extension to add syntax highlight and autocomplete, however it also comes with Theme Check which does not support Canvas
106 | * These settings disable theme check
107 | 
108 | ### End of line character
109 | 
110 | ```json
111 | "files.eol": "\n"
112 | ```
113 | 
114 | * Prevents issues with end of line characters being different
115 | 
116 | ### File associations
117 | 
118 | ```json
119 | "files.associations": {
120 |   "*.scss.liquid": "scss",
121 |   "*.js.liquid": "javascript"
122 | }
123 | ```
124 | 
125 | * This tells VS Code to ignore the `.liquid` extension and open the files with the write sort of highlighting enabled
126 | 
127 | ### Git autofetch
128 | 
129 | ```json
130 | "git.autofetch": true
131 | ```
132 | 
133 | * Autofetches the Git repo every five minutes
134 | 
135 | ### HTML validation
136 | 
137 | ```json
138 | "html.validate.scripts": false,
139 | "html.validate.styles": false
140 | ```
141 | 
142 | * Stops validating `<script>` and `<style>` tags in HTML files
143 | * These are frequently used to pass Liquid variables into global JS
144 | * Because of the presence of Liquid in these tags VS Code's linter flags errors
145 | 
146 | ### Lint on save
147 | 
148 | ```json
149 | "editor.formatOnSave": false,
150 | "editor.codeActionsOnSave": {
151 |   "source.fixAll.eslint": true,
152 |   "source.fixAll.stylelint": true
153 | },
154 | "stylelint.validate": ["css", "scss"]
155 | ```
156 | 
157 | * Runs `eslint --fix` and `stylelint --fix` on file save
158 | * `formatOnSave` is set to `false` to prevent Prettier extension from running (if installed)
159 | * Sets Stylelint extension to validate SCSS files as well as CSS files
160 | 
161 | ### Tab size
162 | 
163 | ```json
164 | "editor.tabSize": 2
165 | ```
166 | 
167 | * You should use a tab size of two spaces to follow guidelines
168 | 
169 | ### Trim trailing whitespace
170 | 
171 | ```json
172 | "files.trimTrailingWhitespace": true
173 | ```
174 | 
175 | * Trims any trailing whitespace on file save (makes linting happy)
176 | 
177 | [← Back to homepage](../README.md)


--------------------------------------------------------------------------------