Skip navigation

Coding convention

One page summary of how to works on Frontend project.

HTML

CSS

Units

For the root element of the DOM, typically represented by the <html> tag, set the font size using pixels (px), as shown below:

html {
  font-size: 16px; /* Some websites may opt for 10px */
}

When specifying breakpoints for media queries, continue to use the pixel unit (px).

For all other CSS properties:

  • Utilize relative units such as %, em, rem, vw, vh, ch, ex, vmin, vmax.
    It's advisable to minimize the use of ch, ex, vmin, and vmax units in our codebase, if possible.

  • Do not employ absolute units such as such as mm, cm, in, pt, pc, px.

We provide a px2rem mixin to facilitate the conversion from pixels (px) to rems (rem). For instance, if the root element has a font-size of 16px, invoking px2rem(32px) will return 2rem.

Naming convention

When it comes to naming conventions, it is strongly recommended that all class names adhere to the BEM (Block Element Modifier) methodology. This recommendation is particularly pertinent when the HTML needs to be integrated by the Backend team. BEM offers the advantage of requiring minimal to no reintegration effort in the event of styling changes. It's worth noting that naming conventions such as Tailwind CSS or other Atomic CSS-like methodologies are not particularly suitable in this context.

However, if the HTML is generated from the client-side or does not necessitate integration by the Backend team, alternative naming conventions can be considered. Nevertheless, even in these cases, BEM remains highly recommended.

Breakpoints

We adopt a mobile-first approach, meaning that CSS rules are initially applied to all screen sizes by default.

For styles that should apply to both tablet and desktop screens, use @include tablet.
For styles exclusive to desktop screens, use @include desktop.

Below are sample mixins for these breakpoints:

@mixin tablet {
  @media (min-width: px2rem(768px)) {
    @content;
  }
}

@mixin desktop {
  @media (min-width: px2rem(1024px)) {
    @content;
  }
}

In most cases, you will only need to use @include tablet for both tablet and desktop unless there are specific differences mentioned in the user story.

Examples

For example, an element with the target class will have a black color on mobile and a blue color on tablet and desktop:

.target {
  color: black;

  @include tablet {
    color: blue;
  }
}

Alternatively, if an element with the target class should have a black color on mobile, a blue color on tablet, and a red color on desktop, you can achieve it like this:

.target {
  color: black;

  @include tablet {
    color: blue;
  }

  @include desktop {
    color: red;
  }
}

Javascript

All new scripts must use TypeScript and follow the ES Module format.

Given that Optimizly CMS is block-based, components may appear multiple times on a page. Ensure that your scripts accommodate this scenario, allowing all blocks to function as expected.

Editorconfig

For new projects that do not have specific coding convention requirements, the following rules should be applied in the .editorconfig file:

.editorconfig file:

root = true

[*]
indent_style = space
indent_size = 2
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
end_of_line = lf
max_line_length = 150

[CHANGELOG.md]
indent_size = false

.prettierrc.yaml file:

# Documentation: https://prettier.io/docs/en/options.html

trailingComma: es5
tabWidth: 2
useTabs: false
semi: true
endOfLine: lf
singleQuote: true
bracketSpacing: true
bracketSameLine: false
arrowParens: always
htmlWhitespaceSensitivity: css
singleAttributePerLine: false

# JSX
jsxSingleQuote: false

# Vue
vueIndentScriptAndStyle: false

Should a customer have specific rules, these should take precedence over the above rules.

To enforce these rules, install Prettier and enable it in Visual Studio Code. Additionally, ensure that Format on Paste and Format on Save are enabled in Visual Studio Code's settings.