add html guidelines

webapp/README.md

@@ -101,6 +101,6 @@ The folder structure we are aiming for is based on the [directory setup proposed
 - **assets** contains icons, images and logos in `svg` format
 - **components** are the generic building blocks of the app – small, reusable and usually not coupled to state
 - **features** are composed of components but tied to a particular function of the app (e.g. `comment` or `post`)
-- **layouts** can use components to create templates for pages
+- **layouts** can use components to create layout templates for pages
 - **pages** are the entry points for all `routes` in the app and are composed of layouts, features and components
 - **styles** holds all shared SCSS files such as `variables` and `mixins`

webapp/html.md

@@ -0,0 +1,22 @@
+# HTML – Code Guidelines
+
+## We write semantic markup
+
+We avoid using `divs` and `spans` and try to choose more meaningful HTML elements instead. If unsure which element to use [this list by MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) can be of help.
+
+Why?
+- semantic markup is crucial for accessibility
+- it makes the code more readable for other developers
+- it benefits our SEO
+
+For more background [see this article](https://css-tricks.com/why-how-and-when-to-use-semantic-html-and-aria/).
+
+This doesn’t mean you can’t ever use a `div` – just think twice before you do!
+
+## We write as little HTML as possible – and as much as necessary
+
+HTML is used to _structure content on the page_ and should therefore reflect its complexity. Not more and not less. Most content does not require deep nesting of HTML elements – if you find yourself wrapping `container` around `container` or adding an element just to correctly position another element on the page this calls for the use of CSS instead!
+
+Why?
+- deep nesting makes it hard to understand, style and maintain components
+- it can lead to performance issues