add scss guidelines

webapp/components.md

@@ -17,8 +17,14 @@ Usually `pages` use `layouts` as templates and will be composed of `features`. `
 
 - 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 `PostTeaser` feature consists of a `LayoutCard` 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.
+
+## We use two-word names
+
+We follow the W3C rules for naming custom elements as suggested in the [Vue.js docs](https://vuejs.org/v2/guide/components-registration.html#Component-Names) to differentiate our own components from regular HTML elements in our templates.
+
+Names should also be meaningful and unique to avoid confusion and code duplication, and also not too long to make them readable. Therefore: aim for two-word names, such as `layout-card`, `post-list` or `post-teaser`.

webapp/scss.md

@@ -0,0 +1,66 @@
+# SCSS - Code Guidelines
+
+## We use classes over tags and ids
+
+Never apply styles to `tags` or `ids` – use `classes` instead!
+
+Why?
+- HTML tags are responsible for the document _structure_, not the looks
+- targeting HTML tags comes with performance issues
+- ids are responsible for identifying a unique element, not for styling it
+- ids have higher specificity than classes and therefore don't play well together
+- classes can be combined and reused while ids are unique
+
+For more background see the following articles on [why not to style tags](https://frontstuff.io/you-need-to-stop-targeting-tags-in-css) and [why not to style ids](https://dev.to/clairecodes/reasons-not-to-use-ids-in-css-4ni4).
+
+## We use design tokens instead of magic numbers
+
+In order to achieve a consistent look and feel we use a set of pre-defined `design tokens` to style our components, for example `colors`, `sizes` and `box-shadows`. These tokens are stored as `SCSS variables` and reused throughout the app.
+
+So, instead of typing _pixel values_ or _hex codes_ make sure you use design tokens such as `height-header` or `color-input-border`.
+
+## We name our classes after components
+
+Our SCSS styles live within the corresponding component (see the [Vue.js docs for single-file components](https://vuejs.org/v2/guide/single-file-components.html) for reference) and should therefore carry the same _unique_ name.
+
+Why?
+- it clearly ties the styles to the one component
+- having unique class names means styles will not be accidentally overwritten in other files
+- we can avoid using `scoped CSS` which [comes with performance caveats](https://vue-loader.vuejs.org/guide/scoped-css.html#also-keep-in-mind)
+
+## We use variants instead of overriding styles
+
+Components will sometimes need to look different depending on the context in which they are used – a button might for example be `green` when it represents a call to action and `red` when it triggers a destructive action. Rather than making the `rounded-button` component `green` by default and then overriding the `color` for, say, the `delete-account` action – use variants! Pass the `rounded-button` a prop, such as `color: danger`, and then apply the respective `variant class`.
+
+Name variant classes with a dash prefix, such as `-danger`, then target them like this:
+
+```scss
+.rounded-button {
+  /* other css styles */
+
+  &.-danger {
+    color: $color-danger;
+  }
+}
+```
+
+## We _style_ within the component, we _position_ when we use it
+
+In order to make components truly reusable it is important to limit their styles to, well, their actual _styling_. What color are they, how big is the text, what happens on `hover`, do they have a rounded border – all that is part of it.
+
+Margins, alignment and positioning on the other hand need to be defined in the _parent_ because the same component might sometimes be aligned to the left, sometimes to the right and sometimes float above other content. For more details see the [rscss guidelines](https://rscss.io/layouts.html).
+
+To do that, use the `child selector`, like this:
+
+```scss
+.login-form {
+  /* other css styles */
+
+  > .rounded-button {
+    margin: $margin-small;
+    justify-self: flex-end;
+  }
+}
+```
+
+A special case are dimensions like `width` and `height`. If it is important that a component always has the same dimensions (the height of a button should be consistent, for example) define it _within the component_ itself, if a component should have flexible dimensions (a card, for example, could stretch over the whole screen in one place and be limited to a certain width in another) define the dimensions _in the parent_.