Richtlinien zum Schreiben von CSS-Codebeispielen

Allgemeine Richtlinien für CSS-Codebeispiele

Ein Format wählen

Die Meinungen über die richtige Einrückung, Leerzeichen und Zeilenlängen gehen seit jeher auseinander. Diskussionen darüber lenken vom Erstellen und Pflegen der Inhalte ab.

Auf MDN Web Docs verwenden wir Prettier zur Codeformatierung, um einen einheitlichen Codestil zu gewährleisten und fachfremde Diskussionen zu vermeiden. Die aktuellen Regeln finden Sie in unserer Konfigurationsdatei; weitere Informationen bietet die Prettier-Dokumentation.

Prettier formatiert den gesamten Code und sorgt für einen einheitlichen Stil. Dennoch gibt es einige zusätzliche Regeln, die Sie beachten müssen.

Planen Sie Ihr CSS

Bevor Sie umfangreichen CSS-Code schreiben, planen Sie Ihre Styles sorgfältig. Welche allgemeinen Styles werden benötigt? Welche unterschiedlichen Layouts müssen Sie erstellen? Welche gezielten Überschreibungen sind erforderlich, und lassen sie sich wiederverwenden? Vor allem sollten Sie versuchen, zu viele Überschreibungen zu vermeiden. Wenn Sie immer wieder Styles schreiben und sie wenige Regeln später wieder aufheben, sollten Sie Ihre Strategie wahrscheinlich überdenken.

Verwenden Sie moderne CSS-Features, wenn sie unterstützt werden

Sie können neue Features verwenden, sobald alle großen Browser – Chrome, Edge, Firefox und Safari – sie unterstützen (siehe Baseline).

Diese Regel gilt nicht für das CSS-Feature, das auf der jeweiligen Seite dokumentiert wird. Dafür gelten stattdessen die Aufnahmekriterien. Sie können beispielsweise nicht standardisierte oder experimentelle Features dokumentieren und vollständige Beispiele schreiben, die deren Verhalten veranschaulichen. Verwenden Sie solche Features jedoch nicht in Demos zu anderen, nicht damit zusammenhängenden Features, etwa einer Web-API.

Befolgen Sie gängige bewährte Vorgehensweisen

Einige allgemein anerkannte Grundsätze müssen wir hier nicht ausführlich erläutern:

• Achten Sie darauf, dass Ihr Code keine Syntaxfehler enthält, durch die eine Property oder Deklaration ignoriert werden könnte. Standardsyntax, die noch nicht implementiert wurde, ist zulässig, sofern sie unserer allgemeinen Regel zu modernen CSS-Features entspricht.
• Verwenden Sie keine nicht standardisierten, veralteten oder obsoleten Features. Diese Richtlinie gilt auch für Features mit Präfix: Verwenden Sie die Variante mit Präfix nur dann, wenn das standardisierte Feature nicht verfügbar ist (siehe unsere allgemeine Regel zu modernen CSS-Features). Wenn Lesende eine breitere Kompatibilität benötigen, können sie selbst eine Fallback-Variante mit Präfix ergänzen oder einen CSS-Postprozessor verwenden.
• Schreiben Sie keinen redundanten oder wirkungslosen Code, da dieser häufig auf Fehler oder Überbleibsel einer Umstrukturierung hinweist. Dazu gehören wiederholte Properties innerhalb eines Deklarationsblocks, leere Deklarationen, leere Kommentare und Selektoren, die auf keine Elemente zutreffen.

Verwenden Sie keine Präprozessoren

Verwenden Sie in Beispielcode keine Präprozessorsyntax wie Sass, Less oder Stylus. Auf MDN Web Docs dokumentieren wir reines CSS. Präprozessoren erschweren lediglich das Verständnis der Beispiele und können Lesende verwirren.

Verwenden Sie keine bestimmten CSS-Methodologien

Schreiben Sie im Sinne der vorherigen Richtlinie auf MDN Web Docs keinen Beispielcode, der einer bestimmten CSS-Methodologie wie BEM oder SMACSS folgt. Obwohl die resultierende Syntax gültiges CSS ist, können die Namenskonventionen Menschen verwirren, die mit diesen Methodologien nicht vertraut sind.

Verwenden Sie keine CSS-Resets

Um CSS plattformübergreifend möglichst umfassend zu kontrollieren, verwendeten früher viele Menschen CSS-Resets: Sie entfernten zunächst sämtliche Styles, um anschließend alles selbst neu aufzubauen. Das hat durchaus Vorteile. Gerade heute können CSS-Resets jedoch übertrieben sein, weil dadurch viel zusätzliche Zeit in die erneute Implementierung von Dingen fließt, die ursprünglich nicht unbedingt problematisch waren – etwa Standardabstände und Listenformatierungen.

Formale Syntax und Pseudocode

Formale Syntax ist ein wesentlicher Bestandteil der CSS-Dokumentation von MDN. Ein Beispiel finden Sie im Abschnitt Formale Syntax auf der Seite zur Property background-image. Da viele Entwicklerinnen und Entwickler mit diesem Syntaxformat vertraut sind, können Sie in Beschreibungen und Beispielen Pseudocode verwenden, der an formale Syntax angelehnt ist. Code, der kein syntaktisch korrektes CSS ist, darf jedoch nicht als CSS gekennzeichnet werden. Syntaxfehler in css-Codeblöcken verhindern, dass statische Prüfprogramme den Code parsen können, verwirren Lesende, die gültigen CSS-Code erwarten, und können sogar zu unsinniger Syntaxhervorhebung führen. Kennzeichnen Sie den Codeblock stattdessen als plain, oder verwenden Sie das Makro CSSSyntaxRaw, um die vollständige formale Syntax darzustellen.

Schreiben Sie Beschreibungen nicht so (dies ist ohnehin keine echte formale Syntax, sondern lediglich Pseudo-CSS mit Platzhaltern):

The `border` property has the following general form:

```css
border: <border-width> <border-style> <border-color>;
```

Verwenden Sie stattdessen plain:

The `border` property has the following general form:

```plain
border: <border-width> <border-style> <border-color>;
```

Oder schreiben Sie, wenn es angemessen erscheint, echte formale Syntax mit dem Makro CSSSyntaxRaw:

The `border` property is specified as a line width, a line style, and a color, in any order:

{{CSSSyntaxRaw(`border = <line-width> || <line-style> || <color>`)}}

Außerdem ist ein einzelner Wert kein syntaktisch korrektes CSS. CSS erfordert mindestens eine Property und ihren Wert. Wenn Sie die Funktion rgb() dokumentieren, schreiben Sie Folgendes:

color: rgb(31 41 59);
color: rgb(31 41 59 / 26%);

Verwenden Sie nicht diesen Stil:

rgb(31 41 59);
rgb(31 41 59 / 26%);

Beachten Sie, dass diese Regel nicht für den ersten Codeblock im Abschnitt „Syntax“ gilt. Für diesen gelten stattdessen die Vorgaben für Syntaxabschnitte, nach denen Funktionen ohne Property-Namen geschrieben werden müssen.

Animationen

Keyframe-Selektoren

Bei der Angabe von Keyframes können die Selektoren 0% und 100% auch als from und to geschrieben werden. Wenn eine @keyframes-Regel nur diese beiden Selektoren enthält, verwenden Sie from und to statt 0% und 100%. Dadurch wird Ihr Code aussagekräftiger.

Vermeiden Sie also Folgendes:

@keyframes example {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

Verwenden Sie stattdessen from und to:

@keyframes example {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

Wenn Ihre @keyframes-Regel hingegen mehr als nur den Anfangs- und den Endzustand enthält, verwenden Sie aus Gründen der Einheitlichkeit die Selektoren 0% und 100%.

@keyframes example {
  0% {
    opacity: 0;
  }
  50% {
    opacity: 0.8;
  }
  100% {
    opacity: 1;
  }
}

Kaskade, Properties und Selektoren

Spezifität steuern

Vermeiden Sie nach Möglichkeit unerwartete Effekte beim Erhöhen oder Verringern der Spezifität, etwa durch übermäßigen Einsatz der Pseudoklasse :where() oder durch das Duplizieren von Selektoren. Ziehen Sie stattdessen folgende Techniken in Betracht, um die Spezifität zu steuern:

• Die Reihenfolge der Deklarationen ändern, um die Kaskade zu nutzen
• Properties innerhalb der Deklarationsblöcke so umordnen, dass sie sich nicht gegenseitig überschreiben
• ID-Selektoren verwenden, wenn das HTML-Attribut id selbst gerechtfertigt ist

!important

!important ist das letzte Mittel und sollte im Allgemeinen nur verwendet werden, wenn Sie etwas überschreiben müssen und es keine andere Möglichkeit gibt. Die Verwendung von !important gilt als schlechte Praxis und sollte möglichst vermieden werden.

.bad-code {
  font-size: 4rem !important;
}

Reihenfolge

Wenn sich zwei Deklarationsblöcke auf dasselbe Element oder dieselben Elemente beziehen, sollte der Block mit der höheren Spezifität im Stylesheet im Allgemeinen später stehen.

button {
  color: blue;
}

.my-form button {
  color: red;
}

Ordnen Sie innerhalb eines Deklarationsblocks zusammengehörige Properties möglichst nebeneinander an, etwa solche für Größe, Positionierung und Farbe. Custom Properties sollten am Anfang des Deklarationsblocks stehen, damit alle verfügbaren Custom Properties schnell zu erkennen sind.

Leerzeilen

Leerzeilen zwischen Deklarationsblöcken werden empfohlen. Sie können darauf verzichten, wenn aufeinanderfolgende Blöcke eng zusammenhängen, etwa bei Varianten derselben Utility-Klasse.

Setzen Sie Leerzeilen zwischen Properties sparsam ein. Fügen Sie sie nur hinzu, wenn jede Property-Gruppe einen klar abgegrenzten inhaltlichen Bereich bildet.

Shorthand-Properties

• Wenn jede einzelne Property einer Shorthand-Property einen Wert erhält, der vom Standardwert abweicht, verwenden Sie die Shorthand-Property statt der einzelnen Longhand-Properties. Dadurch wird Ihr Code kürzer und leichter lesbar.

  Ersetzen Sie diese Longhand-Properties:

  css

  margin-top: 1em;
  margin-right: 2em;
  margin-bottom: 1em;
  margin-left: 2em;
  

  durch die entsprechende Shorthand-Property:

  css

  margin: 1em 2em;
  

• Wenn nur einige der einzelnen Properties einer Shorthand-Property Werte erhalten, die vom Standardwert abweichen, ist die Verwendung der Shorthand-Property optional. Beide Varianten sind zulässig:

  css

  margin-top: 1em;
  margin-bottom: 1em;
  

  css

  margin: 1em 0;
  

• Verwenden Sie die kürzeste verfügbare Shorthand-Syntax. Schreiben Sie:

  css

  margin: 1em;
  

  Vermeiden Sie:

  css

  margin: 1em 1em;
  margin: 1em 1em 1em 1em;
  

• Schreiben Sie Shorthand-Properties in der kanonischen Reihenfolge. Schreiben Sie:

  css

  /* width style color */
  border: 1px solid red;
  

  Schreiben Sie nicht:

  css

  border: solid red 1px;
  

• Verwenden Sie bei jeder Shorthand-Property entweder diese oder ihre einzelnen Longhand-Properties, aber niemals eine Mischung aus beidem. Das Zusammenspiel bei Überschreibungen ist komplex und fehleranfällig. Vermeiden Sie:

  css

  margin-top: 1em;
  margin: 2em; /* Oops, margin-top is ignored */
  
  border-width: 1px;
  border-bottom-width: 5px; /* Overrides one border's width *only* */
  

Verwenden Sie Klassenselektoren

Bevorzugen Sie im Allgemeinen Klassenselektoren (und verwenden Sie in Ihrem HTML class statt id). Klassen sind flexibel einsetzbar: Mehrere Elemente können dieselbe Klasse verwenden, und einem Element können mehrere Klassen zugewiesen werden.

.footnote {
  /* ... */
}

#footnote {
  /* ... */
}

Verwenden Sie Klassen für die Gestaltung und reservieren Sie IDs für Zwecke außerhalb von CSS, beispielsweise für JavaScript oder für Links zu eindeutigen Ankern auf einer Seite (<a href="#section1">). Wenn die Verwendung einer ID gerechtfertigt ist, können Sie sie auch als Selektor einsetzen, gegebenenfalls um die Spezifität zu steuern.

Ältere Schreibweise von Pseudoelement-Selektoren

Die Pseudoelemente ::before, ::after, ::first-letter und ::first-line können auch mit einem einzelnen Doppelpunkt geschrieben werden (etwa :before). Vermeiden Sie diese Schreibweise, da von ihr abgeraten wird und Lesende sie mit einer Pseudoklasse wie :hover verwechseln könnten.

Komplexe Selektorlisten

Die Pseudoklassen :is(), :where() und :not() akzeptieren komplexe Selektorlisten. Nutzen Sie sie, um Ihre Selektoren zu verkürzen.

Schreiben Sie:

input:not(:checked, :disabled) {
  /* ... */
}

Schreiben Sie nicht:

input:not(:checked):not(:disabled) {
  /* ... */
}

Groß- und Kleinschreibung

Standardmäßig sollten alle Bezeichner kleingeschrieben werden. Das gilt für Selektoren, Funktionen und Schlüsselwörter. Benutzerdefinierte Bezeichner sollten Kebab-Case verwenden, etwa --custom-property oder my-animation. Die Konventionen zur Groß- und Kleinschreibung von HTML-IDs und -Klassen, die als CSS-Selektoren referenziert werden, finden Sie im HTML-Stilleitfaden.

Eine Ausnahme bilden Schlüsselwortwerte, die in SVG definiert sind. Aus historischen Gründen verwenden sie camelCase und sollten der Lesbarkeit halber auch so geschrieben werden. Dazu gehören currentColor sowie Werte von text-rendering, shape-rendering, pointer-events und color-interpolation-filters.

Farben

Eine Schreibweise wählen

Wenn die genaue Farbpalette keine Rolle spielt, verwenden Sie grundsätzlich gebräuchliche Farbnamen. Verwenden Sie beispielsweise black statt rgb(0 0 0) oder #000000 und green statt chartreuse.

Wenn eine bestimmte Farbe benötigt wird, verwenden Sie standardmäßig die Schreibweise rgb(). hsl() und andere Funktionen sollten Sie nur verwenden, wenn die jeweilige Darstellungsform eine Bedeutung hat, etwa bei einem Farbkreis oder einem Farbverlauf. Die Hexadezimalschreibweise ist kürzer, kann aber schlechter lesbar sein. Sie können sie anstelle von rgb() verwenden, wenn das für Sie praktischer ist.

Unabhängig davon, welche Farbfunktion Sie verwenden, nutzen Sie immer die moderne Syntax (rgb(31 41 59 / 0.26)) und nicht die ältere, kommagetrennte Syntax. Verwenden Sie die Funktion immer ohne das Suffix a (rgb statt rgba): Das ist kürzer, und Sie müssen den Funktionsnamen nicht ändern, wenn Sie später den Alphakanal hinzufügen oder entfernen.

Verwenden Sie bei der Hexadezimalschreibweise immer die Version mit sechs beziehungsweise acht Stellen, um die Lesbarkeit zu erleichtern: #aabbcc statt #abc.

Farbparameter

Verwenden Sie aus Gründen der Einheitlichkeit für alle Parameter standardmäßig Zahlen statt Prozentangaben oder Gradwerten. Das gilt auch für den Alphakanal. Wenn eine bestimmte Darstellungsform jedoch sinnvoll ist, etwa bei Animationen, Farbverläufen oder Berechnungen, verwenden Sie den für den Kontext passenden Typ.

Wenn der Alphakanal 1 ist, lassen Sie ihn weg. Schreiben Sie rgb(31 41 59) statt rgb(31 41 59 / 1).

Farben auswählen

Zusätzlich zur Empfehlung, gebräuchliche Farbnamen zu verwenden, sollte Ihre Farbpalette unseren Richtlinien zur Barrierefreiheit entsprechen. Wenn Farben Elemente voneinander unterscheiden sollen, etwa ein „rotes Kästchen“ und ein „blaues Kästchen“, achten Sie insbesondere darauf, dass Menschen mit Farbsehschwäche diese Farben unterscheiden können. Streben Sie zwischen Text und Hintergrund ein Kontrastverhältnis von mindestens 4,5:1 an (WCAG AA).

Kommentare

Verwenden Sie CSS-Kommentare, um Code zu erläutern, der nicht für sich selbst spricht. Achten Sie darauf, zwischen den Sternchen und dem Kommentartext jeweils ein Leerzeichen zu lassen.

/* This is a CSS-style comment */

Schreiben Sie Kommentare in eigene Zeilen unmittelbar vor den Code, auf den sie sich beziehen:

h3 {
  /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */
  text-shadow: 1px 1px 2px red;
  /* Sets the font-size to double the default document font size */
  font-size: 2rem;
}

Schriftarten

Schriftfamilien angeben

Fügen Sie bei der Angabe einer Schriftfamilie immer als letzten Fallback den Namen einer generischen Schriftfamilie hinzu. So stellt der Browser den Text in einer besser geeigneten Ersatzschrift dar, wenn die angegebene Schrift nicht verfügbar ist. Websichere Schriftarten sind von dieser Regel ausgenommen.

body {
  font-family: "Helvetica";
}

body {
  /* The "sans-serif" family is not needed because Arial is a web-safe font */
  font-family: "Helvetica", "Arial";
}

math {
  font-family: "Latin Modern Math", "STIX Two Math", math;
}

Schriftstärken angeben

Bevorzugen Sie Schlüsselwortwerte wie normal und bold sowie relative Stärken wie bolder und lighter. Verwenden Sie Zahlenwerte nur, wenn eine bestimmte Schriftstärke gewünscht ist. Ersetzen Sie 400 immer durch normal und 700 durch bold, außer wenn Sie Wertebereiche für variable Schriftarten deklarieren oder die Einheitlichkeit mit anderen ähnlichen Deklarationen wahren möchten.

Längen

Verwenden Sie flexible oder relative Einheiten

Für größtmögliche Flexibilität auf möglichst vielen Geräten sollten Sie für alle Längen standardmäßig relative Einheiten wie em, rem, Prozentwerte und Viewport-Einheiten verwenden (Letztere, wenn die Werte von der Viewport-Breite abhängen sollen). Weitere Informationen finden Sie in unserem Leitfaden zu CSS-Werten und -Einheiten.

Schreiben Sie:

margin: 0.5em;
max-width: 50%;

Vermeiden Sie:

margin: 20px;
max-width: 500px;

Media Queries

Bereichssyntax

Verwenden Sie die moderne Bereichssyntax statt min- und max-. Damit lassen sich exklusive Bereiche sowie obere und untere Grenzen gleichzeitig angeben. Insgesamt ist sie zudem kürzer und leichter lesbar.

@media (width >= 480px) {
  /* ... */
}
@media (600px < height < 900px) {
  /* ... */
}

@media (min-width: 480px) {
  /* ... */
}
@media (min-height: 600px) and (max-height: 900px) {
  /* ... */
}

Dieser Grundsatz gilt auch für die Verwendung von Media Queries außerhalb von CSS, etwa im Attribut media von <link>-Elementen oder in window.matchMedia().

Wenn Sie unterschiedliche alternative Styles anhand von Media-Schwellenwerten auswählen, achten Sie besonders sorgfältig auf Ihre Media Queries. Denken Sie daran, dass width und height auch Bruchwerte annehmen können. Stellen Sie sicher, dass für jeden Wert genau einer der alternativen Styles wirksam ist.

Mobile-First-Media-Queries

Wenn ein Stylesheet Media-Query-Styles für unterschiedliche Viewport-Größen enthält, definieren Sie zuerst die Styles für schmale Bildschirme beziehungsweise Mobilgeräte, bevor die erste Media Query erscheint. Ergänzen Sie anschließend in aufeinanderfolgenden Media Queries die Styles für breitere Viewports. Dieser Ansatz bietet viele Vorteile, die unter Responsives Design erläutert werden.

/* Default CSS layout for narrow screens */

@media (width >= 480px) {
  /* CSS for medium width screens */
}

@media (width >= 800px) {
  /* CSS for wide screens */
}

@media (width >= 1100px) {
  /* CSS for really wide screens */
}

Zeichenfolgen

Setzen Sie überall dort, wo Anführungszeichen in der CSS-Syntax optional sind, doppelte Anführungszeichen. Gehen Sie so vor:

[data-vegetable="liquid"] {
  background-image: url("../../media/examples/lizard.png");
  font-family: "Helvetica", "Arial";
}

Vermeiden Sie Folgendes, da die zulässigen Zeichen dabei stärker eingeschränkt sind und mitunter schwer erkennbare Syntaxfehler entstehen:

[data-vegetable=liquid] {
  background-image: url(../../media/examples/lizard.png);
  font-family: Helvetica, Arial;
}

Geben Sie bei der At-Regel @import den Modulpfad als Zeichenfolge an, nicht als url().

@import "style.css";

@import url("style.css");

Siehe auch

CSS-Referenzindex – auf unseren Referenzseiten zu CSS-Properties finden Sie gute, knappe und aussagekräftige CSS-Beispiele. Die interaktiven Beispiele im Abschnitt „Ausprobieren“ folgen im Allgemeinen den Richtlinien auf dieser Seite.