Coding Standards

Sections and Theme Settings

  • Consistent naming - if in doubt follow Dawn conventions
  • Theme settings should use underscores (‘_’) as separators
  • Theme setting labels (displayed in Theme customiser) should use normal sentence-case - not all caps or title-case
  • Section file names should match their section names as displayed in the Theme Customiser
  • Sections and snippets specific to a page or section should be prefixed with the page or section type - e.g. Sections: footer_credits, product-recommendations. Snippets: product__form, blog__read-time

CSS

  • Use tailwind classes where it makes sense. Try to avoid redeclaring CSS that is already covered by Tailwind.
  • Use BEM class names in liquid markup and add Tailwind classes to CSS files using @apply
  • Create CSS files for sections or individual features in _src/styles and match CSS file names to their liquid counterparts
  • Colours and fonts, where possible, should be defined as CSS custom properties in _src/snippets/theme-settings.liquid and passed to ./tailwind.config.js after which they will be available as Tailwind CSS classes

JavasScript

  • Custom JavaScript files are placed in _src/styles
  • JavaScript should be included only when required - i.e. if a section is not used on a page, its related JS should not be included
  • Use deferred loading of JavaScript whenever possible
  • Avoid the use of jQuery, use vanilla JavaScript instead

Icons

  • Icons should be in SVG format where possible
  • Icons files are placed in _src/icons - and referenced in liquid using snippets/icon.liquid
  • Avoid using inline SVGs in liquid or Base64 encoded SVGs in CSS

Images and Theme Assets

  • Images, font or other assets required by the theme should be placed in assets/
  • Images or videos controlled by the end-user (in the theme customiser) should be uploaded through the Theme Customiser or Settings > Files

Screen resolutions

  • 1440px < Widescreen desktop
  • 1280 > 1440 Widescreen Laptops, Desktop
  • 1080 > 1280 Laptops
  • 768 > 1024 Tablet (incl ipad pro)
  • 375 > 769 Modern mobiles
  • < 375 Legacy mobiles

To Do

  1. CSS guidelines: workflow (postcss, tailwind), structure, Tailwind classes, naming, …
  2. JS guidelines: workflow, structure, load on demand, dependencies & frameworks
  3. Liquid: formating, file structure & naming
    1. Sections: style, js, markup structure - schema blocks and settings: naming, values and basic settings that should be on all sections
    2. Snippets: reusing
  4. Icons
  5. Assets
  6. Workflow tools: linters, CLI, …