coding-conventions.md

Coding Conventions

Where to put properties for various states

The declaration block for the pseudo-class name only lists the properties for which the value changes in the related state. Properties that remain unchanged in all other states are part of the declaration block for the general class name, even if they don’t affect the element’s initial state.

Do this

This link receives an underline when the user’s pointer hovers over it. Still, we define its thickness and offset for the initial state.

.ams-link {
  text-decoration: none;
  text-decoration-thickness: 0.125rem;
  text-underline-offset: 0.1667em;

  &:hover {
    text-decoration: underline;
  }
}

Do not do this

.ams-link {
  text-decoration: none;

  &:hover {
    text-decoration: underline;
    text-decoration-thickness: 0.125rem;
    text-underline-offset: 0.1667em;
  }
}

Use mixins for patterns and resets

We use Sass mixins to extract common patterns, especially if they need more than 1 declaration. We collect reset styles in mixins as well. Both the name of the mixins and their documentation help explain the approach.

Form validation styling

We style both the native invalid state (:invalid) as the invalid state you can set manually, using aria-invalid. We’re currently not sure how our users will implement forms, which is why both options are supported. Native form validation isn’t without its issues though, so we might only support manual validation in the future.