add component guidelines

webapp/README.md

@@ -40,7 +40,7 @@ We ensure the quality of our frontend code by using
 - [Jest](https://jestjs.io/) and [Vue Test Utils](https://vue-test-utils.vuejs.org/) to unit test our components
 - [Storybook](https://storybook.js.org/) to manually test our components in an isolated playground
 
-Use these commands to run the tests:
+For more information see our [frontend testing guide](testing.md). Use these commands to run the tests:
 
 {% tabs %}
 {% tab title="With Docker" %}
@@ -101,5 +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`)
-- **pages** are the entry points for all `routes` in the app and are composed of features and components
+- **layouts** can use components to create 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/components.md

@@ -1,5 +1,24 @@
-# COMPONENTS
+# Components – Code Guidelines
 
-The components directory contains your Vue.js Components.
+## We adhere to the [single responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle)
 
-_Nuxt.js doesn't supercharge these components._
+Each component does _exactly one job_. The goal is to end up with many small components that are:
+- easy to understand
+- easy to maintain
+- easy to reuse
+
+**How do you decide what is a separate component?** Try to describe what it does in _one sentence_! When you find yourself using `and` and `or` the code you are talking about should probably be split up into two or more components.
+
+On the other hand, when something is easily expressed in a few lines of HTML and SCSS and not likely to be reused this is a good indicator that it should _not_ go into a separate component.
+
+## We compose with components
+
+Usually `pages` use `layouts` as templates and will be composed of `features`. `features` are composed of `components`, the smallest building blocks of the app. The further down we go in this hierarchy the simpler and more generic the components become. Here is an example:
+
+- The `index` page is responsible for displaying a list of posts. It uses the `default` layout and the `PostList` feature.
+- The `PostList` feature uses a `List` component to render `PostTeaser` features.
+- The `PostTeaser` feature consists of a `Card` wrapped around a `CardImage`, `CardTitle` and `CardContent` component.
+
+The `index` page is unique in the app and will never be reused. The `PostList` knows it is handling post data and can therefore not be used for anything else – but it can display posts on the `index` as well as the `user` page.
+
+The `Card` on the other hand does not care about the type of data it needs to handle. It just takes whatever it receives and renders it in a certain way, so it can be reused throughout the app for many different features.