Merge pull request #9 from zweitag/resolve-external-links

Resolve external links

Author: ChristianPeters

README.md

@@ -1,6 +1,8 @@
 # Zweitag Approach to Scalable and Adaptable Frontends (ZASAF)
 
-[Einleitung zur Wichtigkeit von CSS Guidelines](http://cssguidelin.es/#introduction)
+Bei der Arbeit an großen, langlebigen Projekten mit vielen Entwicklern unterschiedlicher Spezialisierungen und Fähigkeiten ist es wichtig, dass alle einheitlich arbeiten, um Stylesheets sowohl pflegbar als auch skalierbar zu halten und um zu gewährleisten, dass der Code transparent und lesbar bleibt.
+
+Aus diesem Antrieb heraus entstand dieser Styleguide, der es Entwicklern ermöglichen soll, die Code-Qualität hochzuhalten, die Code-Konsistenz zu wahren und produktiver zu arbeiten.
 
 ZASAF folgt dem Grundgedanken von [BEM](http://getbem.com/) und [SMACSS](http://smacss.com), dass Frontends modular aufgebaut werden sollten.
 Dabei unterscheiden wir jedoch noch einmal zwischen generischen und spezifischen Komponenten.
@@ -140,7 +142,7 @@ Die Syntax von BEM finden wir jedoch etwas sperrig und haben uns für ein andere
       .fact-list__entry
         list-style-type: discline-height: 1.2
       .fact-list__entry--highlighted
-        font-weight: bold
+        font-weight: 700
       </pre>
     </td>
     <td>
@@ -150,14 +152,14 @@ Die Syntax von BEM finden wir jedoch etwas sperrig und haben uns für ein andere
       .fact-list--entry
         line-height: 1.2
         &.highlighted
-          font-weight: bold
+          font-weight: 700
       </pre>
     </td>
   </tr>
 </table>
 
 * Der Komponenten-Namensraum wird also mit `--` vom Elementnamen abgegrenzt.
-* Modifier kommen ohne Namensraum aus, da sie ausschließlich in Kombination mit einer Komponente bzw. einem Element eingesetzt werden
+* Modifier kommen ohne Namensraum aus, da sie ausschließlich in Kombination mit einer Komponente bzw. einem Element eingesetzt werden.
 
 ### Beispiel
 
@@ -211,11 +213,15 @@ Die Syntax von BEM finden wir jedoch etwas sperrig und haben uns für ein andere
   +column(8)
  ```
 
+### Anpassung von Komponenten
+
+Um ein und dieselbe Komponente auf unterschiedliche Art und Weise zu stylen, [gibt es folgende Optionen.](customizing-components.md)
+
 ## Globales und Hilfsmittel
 
 ### Globales
 
-Im Order `globals` finden sich globale Basisstile und Konfigurationen:
+Im Order `globals` befinden sich globale Basisstile und Konfigurationen:
 
 * _base.css.sass: Styling der HTML-Elemente (z.B. `strong {font-weight: 700}`)
 * _colors.css.sass: Farbdeklarationen (z.B. `$color-accent: $curious-blue`)
@@ -225,22 +231,16 @@ Im Order `globals` finden sich globale Basisstile und Konfigurationen:
 
 ### Hilfsmittel
 
-Im Ordner `utilitis` finden sich Mixins, die in Komponenten eingesetzt werden können:
+Im Ordner `utilities` befinden sich Mixins, die in Komponenten eingesetzt werden können:
 
 * _clearfix.css.sass
 * _font-smoothing.css.sass
 * _grid.css.sass
 * _responsify.css.sass
 * …
 
-## Best Practices
-
-* [Customizing Components](customizing-components.md)
-* [CSS Best Practices](css-best-practices.md)
-* [Portability](http://cssguidelin.es/#portability)
-* [Specificity](http://cssguidelin.es/#specificity)
-
-## Style Guides
+## Style Guides & Best Practices
 
 * [Haml Style Guide](haml-style-guide.md)
 * [Sass Style Guide](sass-style-guide.md)
+* [CSS Best Practices](css-best-practices.md)

css-best-practices.md

@@ -1,5 +1,7 @@
 # CSS Best Practices
 
+Die Grundvoraussetzung für wartbares, leicht zu lesendes CSS ist eine niedrige Spezifität. Das CSS sollte so geschrieben werden, dass der Selektor spezifisch für das zu stylende Element ist. Dadurch wird ein Selektorstreit aus dem Weg gegangen und ein unnötiges Überschreiben von Selektoren vermieden (Ausnahmen bilden Modifier).
+
 ## Selektorregeln
 
 ### Vermeide zu generische Selektoren
@@ -74,20 +76,42 @@ a.back
 
 ### Vermeide Nachfahrenselektoren
 
-Der Nachfahrenselektor ist der teuerste Selektor in CSS. Gib dem entsprechenden Element besser eine Klasse und style es direkt.
+Der Nachfahrenselektor ist der teuerste Selektor in CSS. Die Verschachtelung von Selektoren muss auf ein Minimum reduziert werden. Gib dem entsprechenden Element besser eine Klasse und style es direkt.
 
 **schlecht**
 
 ``` sass
 .link-list li a
 ```
 
+**genauso schlecht**
+
+``` sass
+.link-list .link-list--link
+```
+
 **gut**
 
 ``` sass
 .link-list--link
 ```
 
+### Vermeide ID-Selektoren
+
+Es gibt zwei Gründe, warum man ID-Selektoren nicht fürs Styling verwenden sollte. Zum einen schraubt eine ID die Spezifität hoch, die im Grunde nur mit Nutzung einer weiteren ID wieder überschrieben werden kann. Das spricht gegen unser Mantra, die Spezifitäät niedrig zu halten (s.o.). Zum anderen müssen IDs im Markup einzigartig sein, woraus folgt, dass man Komponenten mit IDs nicht wiederverwenden kann.
+
+**schlecht**
+
+``` sass
+#navigation
+```
+
+**gut**
+
+``` sass
+.navigation
+```
+
 ### Vermeide den selben Selektor fürs Styling (CSS) und fürs Verhalten (JS) zu verwenden
 
 Separation of concerns. Möchte man Javascript auf ein Element anwenden, hat es sich etabliert, hierfür ein `data-*`Attribut zu nutzen. Der Vorteil: Ändert man später nochmal das Klassenattribut, bleibt das Javascript weiterhin in Takt.

customizing-components.md

@@ -1,4 +1,4 @@
-## How do I customize components?
+# How do I customize components?
 
 The ZASAF follows the Convention over Configuration principle: You should write components that come with good defaults.
 If you want to deviate from the default there are two options:
@@ -9,7 +9,7 @@ If you want to deviate from the default there are two options:
 Each of those options come with its own pros and cons, so choose carefully.
 Translate your rule into a human-understandable sentence – is this what you want to declare?
 
-### Example
+## Example
 
 ``` haml
 .product-page
@@ -27,7 +27,7 @@ Translate your rule into a human-understandable sentence – is this what you wa
 So we start with a basic `.teaser` component in the sidebar of the `.product-page`.
 Now we look at the PSD or HTML or whatever the designer gave us and observe that this teaser should be more grayish than normal.
 
-#### Option 1: Add a modifier
+### Option 1: Add a modifier
 
 ``` sass
 .teaser
@@ -65,7 +65,7 @@ Examples:
   …
 ```
 
-#### Option 2: Location-based customization
+### Option 2: Location-based customization
 
 Now you are saying: "This particular teaser should be unobtrusive."
 

haml-style-guide.md

@@ -1,8 +1,8 @@
-## HAML best practices
+# HAML Styleguide
 
 Because of the importance indentation has on how your code is rendered, the indents should be consistent throughout the document. Any differences in indentation will throw an error. It's common-practice to use two spaces.
 
-### How to use HTML elements
+## How to use HTML elements
 
 To write your tags, use the percent sign followed by the name of the tag
 
@@ -30,7 +30,7 @@ If you want to add multiple classes, simply chain them:
 .container.large.unobtrusive
 ```
 
-### How to use comments
+## How to use comments
 
 There’re three different styles to write comments in Haml.
 
@@ -56,11 +56,11 @@ There’re three different styles to write comments in Haml.
 
 **Note:** Single and multiline comments will be redenred into the document. Therefore we commonly choose the third option because usually comments are meant for developers only.
 
-### Use blocks
+## Use blocks
 
 HAML isn’t Ruby, but it still incorporates some convenient elements of it, and there’s no better example of that than the block syntax.
 
-#### Morph code into block format with `precede`, `succeed` and `surround`
+### Morph code into block format with `precede`, `succeed` and `surround`
 
 **Example:**
 
@@ -93,7 +93,7 @@ Using inline HTML and `content_tag`
 
 This isn’t terrible, but the above blocks are much more readable!
 
-#### Use `link_to` as a block
+### Use `link_to` as a block
 
 When wrapping long or multiple elements in a link tag, It’s wise to use `link_to` in block format.
 
@@ -125,7 +125,7 @@ Rails routing is best used with its built-in helper methods, where objects can b
 %a{href: users_path(@user)} View User Profile
 ```
 
-#### Use `list_of`
+### Use `list_of`
 
 A lesser known – and thus, lesser used – feature of HAML is `list_of`.
 This method generates * elements for you as you iterate over a list of items.
@@ -158,7 +158,7 @@ Whitespace abuse. Every time you use `list_of`, you’ve saved one indentation.
         = link_to student.name, [course, student]
 ```
 
-### Use filters
+## Use filters
 
 Use the colon to define [Haml filters](http://haml.info/docs/yardoc/file.REFERENCE.html#filters). This allows you to pass an indented block of text as input to another filtering program and add the result to the output of Haml.
 
@@ -176,7 +176,7 @@ Use the colon to define [Haml filters](http://haml.info/docs/yardoc/file.REFEREN
   console.log('This is inline script');
 ```
 
-### Use curly braces
+## Use curly braces
 
 The name of the game here is readability and a big part of readability is DRY.
 
@@ -206,7 +206,7 @@ Note that you can also pass in hashes directly into the data attribute, and it w
 .profile(data-name='Popeye' data-favorite-food='Spinach') Loading
 ```
 
-### Use alternative expression methods
+## Use alternative expression methods
 
 At this point, you know exactly what `-` and `=` do in your HAML views, but what about the other fun Ruby expression outputting methods? These alternative outputting methods have got to be some of the most underused features of HAML, yet is one of the most useful, especially for internal communication.
 
@@ -256,6 +256,6 @@ When you don’t know about interpolated Ruby code, you’re bound to pull this
 
 Don’t bother with these strings – just cut right into the interpolated input expressed above and save characters and eye strain.
 
-### HAML Cheat-Sheet
+## HAML Cheat-Sheet
 
 * https://www.cheatography.com/specialbrand/cheat-sheets/haml/

sass-style-guide.md

@@ -183,9 +183,8 @@ Zum Testen unseres Sass-Codes benutzen wir [Sass Lint](https://github.com/sassto
 Die Verwendung des Linters für neue Projekte ist **Pflicht**, damit Styleguide-Fragen in dem Projekt gar kein Thema werden.
 
 * Dafür sollte jeder Entwickelnde lokal [die Editor-Integration](https://github.com/sasstools/sass-lint#ide-integration) verwenden, damit Fehler frühestmöglich erkannt werden.
-  * Falls die Editor-Integration keine Option sein sollte, bliebe auch die Möglichkeit eines Pre-Commit-Hooks.
-* Als zusätzliches Sicherheitsnetz sollte ein Check auf Pull-Request-Ebene existieren.
-  *(Hierfür testen wir gerade die TravisCI-Integration.)*
+* Falls die Editor-Integration keine Option sein sollte, bliebe auch die Möglichkeit eines Pre-Commit-Hooks.
+* Als zusätzliches Sicherheitsnetz sollte ein Check auf Pull-Request-Ebene existieren. Hierfür stellen wir eine TravisCI-Integration zur Verfügung.
 
 ### Installation