Die folgenden Richtlinien behandeln das Schreiben von CSS-Beispielcode für MDN Web Docs.

Allgemeine Richtlinien für CSS-Codebeispiele

Format wählen

Meinungen zur richtigen Einrückung, Leerzeichen und Zeilenlängen sind immer umstritten gewesen. Diskussionen zu diesen Themen lenken von der Erstellung und Pflege von Inhalten ab.

Auf MDN Web Docs verwenden wirPrettier als Code-Formatter, um den Code-Stil konsistent zu halten (und um Themenfremde Diskussionen zu vermeiden). Sie können unsereKonfigurationsdatei einsehen, um die aktuellen Regeln zu erfahren, und diePrettier-Dokumentation lesen.

Prettier formatiert den gesamten Code und hält den Stil konsistent. Dennoch gibt es einige zusätzliche Regeln, die Sie befolgen müssen.

Planen Sie Ihr CSS

Bevor Sie sich in das Schreiben großer CSS-Abschnitte stürzen, planen Sie Ihre Styles sorgfältig. Welche allgemeinen Styles werden benötigt, welche unterschiedlichen Layouts müssen erstellt werden, welche spezifischen Überschreibungen müssen erstellt werden, und sind sie wiederverwendbar? Vor allem sollten Sie versuchen,zu viele Überschreibungen zu vermeiden. Wenn Sie feststellen, dass Sie ständig Styles schreiben und sie dann ein paar Regeln weiter wieder aufheben, müssen Sie wahrscheinlich Ihre Strategie überdenken.

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

Sie können neue Funktionen verwenden, sobald sie von jedem großen Browser — Chrome, Edge, Firefox und Safari — unterstützt werden (auch bekannt alsBaseline).

Diese Regel gilt nicht für die CSS-Funktion, die auf der Seite dokumentiert wird (welche stattdessen durch dieKriterien für die Aufnahme bestimmt wird). Zum Beispiel können Sienicht standardisierte oder experimentelle Funktionen dokumentieren und vollständige Beispiele schreiben, die ihr Verhalten demonstrieren, aber Sie sollten davon absehen, diese Funktionen in den Demos für andere nicht verwandte Funktionen wie eine Web-API zu verwenden.

Folgen Sie allgemeinen Best Practices

Es gibt einige allgemein anerkannte Prinzipien, die wir hier nicht ausführlich darlegen müssen:

• Stellen Sie sicher, dass Ihr Code keine Syntaxfehler enthält, die dazu führen können, dass dieEigenschaft oder die Deklaration ignoriert wird. Standard-Syntax, die noch nicht implementiert wurde, ist akzeptabel, wenn sie zu unsererallgemeinen Regel über moderne CSS-Funktionen passt.
• Verwenden Sie keinenicht standardisierten, veralteten oder überholten Funktionen. Diese Richtlinie erstreckt sich aufpräfixierte Funktionen: Verwenden Sie die präfixierte Alternativenur dann, wenn die Standardfunktion nicht verfügbar ist (siehe unsereallgemeine Regel über moderne CSS-Funktionen). Wenn der Leser eine breitere Kompatibilität benötigt, kann er entweder das präfixierte Fallback selbst hinzufügen oder einen CSS-Postprozessor verwenden.
• Vermeiden Sie redundanten oder nicht funktionierenden Code, der ein häufiges Anzeichen für Bugs oder Überbleibsel von Refaktorisierungen ist. Dazu gehören wiederholte Eigenschaften in einer Deklaration, leere Deklarationen, leere Kommentare oder Selektoren, die keine Elemente treffen.

Verwenden Sie keine Präprozessoren

Verwenden Sie in den Beispielcodes keine Präprozessor-Syntax wieSass,Less oderStylus. Auf MDN Web Docs dokumentieren wir die native CSS-Sprache. Die Verwendung von Präprozessoren würde die Barriere zum Verständnis der Beispiele erhöhen und potenziell Leser verwirren.

Verwenden Sie keine spezifischen CSS-Methodologien

Im selben Sinne wie die vorherige Richtlinie sollten Sie keine Beispielcodes auf MDN Web Docs mit einer spezifischen CSS-Methodologie wieBEM oderSMACSS schreiben. Selbst wenn sie gültige CSS-Syntax sind, können die Namenskonventionen für Personen verwirrend sein, die mit diesen Methodologien nicht vertraut sind.

Verwenden Sie keine Resets

Um maximale Kontrolle über CSS auf verschiedenen Plattformen zu haben, haben viele Menschen früher CSS-Resets verwendet, um alle Styles zu entfernen und anschließend alles neu aufzubauen. Das hat sicherlich seine Vorzüge, aber besonders in der modernen Welt können CSS-Resets überflüssig sein, was zu viel zusätzlicher Zeit führt, die für das Neuimplementieren von Dingen aufgebracht wird, die von Anfang an nicht vollkommen kaputt waren, wie z.B. Standartränder und Listenstile.

Formale Syntax und Pseudocode

Formale Syntax ist ein integraler Bestandteil der CSS-Dokumentation von MDN (als Beispiel, siehe den AbschnittFormale Syntax auf der Seite zur Eigenschaftbackground-image). Da viele Entwickler mit Syntax in diesem Format vertraut sind, ist es akzeptabel, Pseudocode in einer formalsyntaxähnlichen Art in Beschreibungen und Beispielen zu schreiben. Jedoch sollte jeder Code, der nicht syntaktisch korrekt geformtes CSS ist, nicht als CSS markiert werden. Syntaxfehler incss Codeblöcken führen dazu, dass der Code von statischen Prüfern nicht geparst werden kann, Leser verwirren, die gültigen CSS-Code erwarten, und sogar zu unsinnigem Syntax-Highlighting führen können. Markieren Sie Ihren Codeblock entweder alsplain, oder verwenden Sie dasCSSSyntaxRaw Makro, um die vollständige formale Syntax zu rendern.

Schreiben Sie keine Beschreibungen wie diese (das ist ohnehin keine echte formale Syntax; es ist nur Pseudo-CSS mit einigen Platzhaltern):

The `border` property has the following general form:```cssborder: <border-width> <border-style> <border-color>;```

Stattdessen verwenden Sieplain:

The `border` property has the following general form:```plainborder: <border-width> <border-style> <border-color>;```

Oder, wenn Sie es für angemessen halten, schreiben Sie die tatsächliche formale Syntax mit demCSSSyntaxRaw Makro:

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>`)}}

Darüber hinaus ist ein einzelner Wert kein syntaktisch gut geformtes CSS. CSS-Code erfordert mindestens eine Eigenschaft und ihren Wert. Wenn Sie diergb() Funktion dokumentieren, schreiben Sie dies:

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, der stattdessen durchSyntax-Abschnitte spezifiziert wird und erfordert, dass Funktionen ohne den Eigenschaftsnamen geschrieben werden.

Animationen

Keyframe-Selektoren

Bei der Angabe von Keyframes können die0% und100% Selektoren auch alsfrom undto geschrieben werden. Wenn eine@keyframes-Regelnur diese beiden Selektoren enthält, verwenden Siefrom undto anstelle von0% und100%. Das macht Ihren Code semantischer.

Vermeiden Sie also dies:

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

Verwenden Sie stattdessenfrom undto:

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

Andererseits, wenn Ihre@keyframes Regel mehr als nur die Start- und Endframes enthält, verwenden Sie die0% und100% Selektoren für Einheitlichkeit.

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

Kaskade, Eigenschaften und Selektoren

Kontrolle der Spezifität

Vermeiden Sie nach Möglichkeit Überraschungen bei der Erhöhung oder Verringerung der Spezifität, wie z.B. das übermäßige Verwenden der:where() Pseudoklasse oder das Duplizieren von Selektoren. Überlegen Sie stattdessen folgende Techniken, um die Spezifität zu verwalten:

• Ändern der Reihenfolge der Deklarationen, um die Kaskade zu nutzen
• Neuanordnung von Eigenschaften in jeder Deklaration, sodass sie sich nicht gegenseitig überschreiben
• Verwendung von ID-Selektoren, in Fällen, in denen das HTML-id selbst gerechtfertigt ist

!important

!important ist das letzte Mittel, das in der Regel nur verwendet wird, wenn Sie etwas überschreiben müssen und es keinen anderen Weg gibt, dies zu tun. Die Verwendung von!important ist eine schlechte Praxis und Sie sollten es so weit wie möglich vermeiden.

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

Reihenfolge

Generell sollte bei zwei Deklarationen, die auf dasselbe Element/dieselben Elemente abzielen, die mit höherer Spezifität später im Stylesheet kommen.

button {  color: blue;}.my-form button {  color: red;}

Innerhalb einer Deklaration sollten verwandte Eigenschaften (wie z.B. für Größenanpassung, Positionierung und Farbe) zusammen platziert werden. Benutzerdefinierte Eigenschaften sollten oben im Deklarationsblock deklariert werden, damit alle verfügbaren benutzerdefinierten Eigenschaften schnell identifiziert werden können.

Leere Zeilen

Leere Zeilen zwischen Deklarationsblöcken werden empfohlen. Sie können sie entfernen, wenn aufeinanderfolgende Deklarationen hochgradig verwandt sind, wie z.B. Variationen derselben Dienstprogrammkategorie.

Leere Zeilen zwischen Eigenschaften sollten sparsam verwendet werden. Fügen Sie sie nur hinzu, wenn jede Gruppe von Eigenschaften einen klaren semantischen Block bildet.

Kurzschreibweise von Eigenschaften

• Wennjede Bestandteil-Eigenschaft einer Kurzschreibweise einen nicht standardmäßigen Wert zugewiesen hat, verwenden Sie stattdessen die Kurzschreibweise, um den Code kürzer und besser lesbar zu machen.

  Ersetzen Sie diese durch Langform-Eigenschaften:

  css

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

  durch ihre entsprechende Kurzform:

  css

  margin: 1em 2em;

• Wenn nureinige Bestandteil-Eigenschaften einer Kurzschreibweise einen nicht standardmäßigen Wert zugewiesen haben, ist die Verwendung der Kurzschreibweise optional. Beide sind akzeptabel:

  css

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

  css

  margin: 1em 0;

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

  css

  margin: 1em;

  Vermeiden Sie diese:

  css

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

• Schreiben Sie Kurzschreibweise-Eigenschaften in derkanonischen Reihenfolge. Schreiben Sie dies:

  css

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

  Schreiben Sie nicht dies:

  css

  border: solid red 1px;

• Für jede Kurzform verwenden Sie entweder diese oder ihre Bestandteile in Langform, und niemals eine Mischung aus beidem, da das Überschreibungsverhältnis komplex und fehleranfällig ist. Vermeiden Sie dies:

  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

Generell bevorzugen SieKlassenselektoren (und verwenden Sieclass anstelle vonid in Ihrem HTML). Sie können zusammengesetzt werden: mehrere Elemente können dieselbe Klasse verwenden, und dieselbe Klasse kann für mehrere Elemente verwendet werden.

.footnote {  /* ... */}

#footnote {  /* ... */}

Verwenden Sie Klassen für die Gestaltung, und reservieren Sie IDs für Zwecke außerhalb von CSS, wie z.B. für die Verwendung in JavaScript oder für Verlinkungen zu eindeutigen Seitenankern (<a href="#section1">). In dem Fall, dass die Verwendung von ID gerechtfertigt ist, können Sie es als Selektor verwenden, um ggf.die Spezifität zu kontrollieren.

Alte Pseudo-Element-Selektoren

Die::before,::after,::first-letter und::first-linePseudoelemente können auch mit einem einzelnen Doppelpunkt geschrieben werden (wie:before). Vermeiden Sie die einzelner-Doppelpunkt-Syntax, da sie nicht empfohlen wird und von Lesern möglicherweise alsPseudoklasse (:hover) missverstanden werden könnte.

Komplexe Selektorenlisten

Die:is(),:where(), und:not() Pseudoklassen akzeptierenkomplexe Selektorenlisten. Verwenden Sie sie, um Ihren Selektor zu verkürzen.

Schreiben Sie dies:

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

Schreiben Sie nicht dies:

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

Groß- und Kleinschreibung

Standardmäßig sollten alle Bezeichner kleingeschrieben sein. Dies gilt für Selektoren, Funktionen und Schlüsselwörter. Benutzerdefinierte Bezeichner sollten dasKebab-Case verwenden, wie--custom-property odermy-animation. Siehe denHTML-Stil-Leitfaden für Konventionen zur Groß- und Kleinschreibung von HTML-IDs und Klassen, die als CSS-Selektoren referenziert werden.

Ausnahmen sind Schlüsselwortwerte, die in SVG definiert sind und aus historischen Gründen imCamelCase geschrieben sind und so zur Verbesserung der Lesbarkeit geschrieben werden sollten. Diese Schlüsselwörter umfassen:currentColor,text-rendering-Werte,shape-rendering-Werte,pointer-events-Werte undcolor-interpolation-filters-Werte.

Farben

Wahl einer Notation

Im Allgemeinen, wenn die spezifische Farbpalette keine Rolle spielt, verwenden Sie gängige benannte Farben als Standard. Zum Beispiel, verwenden Sieblack anstelle vonrgb(0 0 0) oder#000000, undgreen anstelle vonchartreuse.

Wenn eine spezifische Farbe benötigt wird, verwenden Sie standardmäßig diergb()-Notation.hsl() und andere Funktionen sollten nur dann verwendet werden, wenn die jeweilige Darstellung eine Bedeutung hat (zum Beispiel ein Farbkreis oder ein Verlauf). Die hexadezimale Notation ist kürzer, aber möglicherweise weniger lesbar; sie ist austauschbar mitrgb(), je nachdem, was für Sie bequemer ist.

Welche Farb-Funktion auch immer Sie verwenden, verwenden Sie immer das moderne Syntax (rgb(31 41 59 / 0.26)), nicht die veraltete, durch Kommas getrennte. Verwenden Sie immer die Funktion ohne dasa-Suffix (rgb anstelle vonrgba), da es kürzer ist und keinen Namenswechsel erfordert, wenn Sie später entscheiden, den Alpha-Kanal hinzuzufügen oder zu entfernen.

Bei Verwendung der hexadezimalen Notation, verwenden Sie immer die sechs (oder acht) stellige Version, um die kognitive Belastung zu vermeiden:#aabbcc anstelle von#abc.

Farbparameter

Aus Gründen der Konsistenz sollten alle Parameter standardmäßig Zahlen anstelle von Prozentwerten oder Gradzahlen verwenden. Dies gilt auch für den Alpha-Kanal. Wenn jedoch eine bestimmte Darstellung sinnvoll ist (zum Beispiel in Animationen, Verläufen oder Berechnungen), verwenden Sie den geeigneten Typ im Kontext.

Wenn der Alpha-Kanal1 ist, lassen Sie ihn weg. Schreiben Siergb(31 41 59) anstelle vonrgb(31 41 59 / 1).

Farben auswählen

Zusätzlich zur Empfehlung, gängige benannte Farben zu verwenden, sollte Ihre Farbpalette unsereRichtlinien zur Barrierefreiheit erfüllen. Insbesondere sollten die Farben unterscheidbare Elemente (wie eine "rote Box" und eine "blaue Box") für Menschen mit Farbsehschwäche sicherstellen. Streben Sie ein Kontrastverhältnis von mindestens 4,5:1 anKontrastverhältnis (WCAG AA) zwischen Text und Hintergrund.

Kommentare

Verwenden Sie CSS-Kommentarsyntax, um Code zu kommentieren, der nicht selbsterklärend ist. Beachten Sie auch, dass Sie einen Abstand zwischen die Sternchen und den Kommentar einfügen sollten.

/* This is a CSS-style comment */

Stellen Sie Ihre Kommentare auf separate Zeilen, die dem Code vorausgehen, auf den sie sich beziehen, so:

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

Bei der Angabe einer Schriftfamilie fügen Sie immer einen Namen für einegenerische Schriftfamilie als letztes Fallback hinzu. Dies stellt sicher, dass, wenn die angegebene Schrift nicht verfügbar ist, der Browser eine geeignetere Ersatzschrift anzeigt.Websichere Schriften 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;}

Schriftgewichte angeben

Bevorzugen Sie Schlüsselwertangaben wienormal undbold, und relative Gewichte wiebolder undlighter. Verwenden Sie nur Zahlenwerte, wo das spezifische Gewicht erwünscht ist. Sie sollten immer400 durchnormal und700 durchbold ersetzen, außer beim Erklären von Bereichen mit variablen Schriften oder zur Konsistenz mit anderen ähnlichen Deklarationen.

Längen

Verwenden Sie flexible/relative Einheiten

Für maximale Flexibilität über die größtmögliche Bandbreite an Geräten sollten standardmäßig relative Einheiten wieem,rem, Prozentsätze und Viewport-Einheiten (wenn Sie möchten, dass sie abhängig von der Breite des Viewports variieren) für alle Längen verwendet werden. Lesen Sie dazu mehr in unseremLeitfaden zu CSS-Werten und -Einheiten.

Schreiben Sie dies:

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

Vermeiden Sie dies:

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

Media Queries

Bereichs-Syntax

Verwenden Sie die moderne Bereichs-Syntax anstelle vonmin- undmax-. Die erste erlaubt es, exklusive Bereiche zu spezifizieren, ermöglicht die gleichzeitige Angabe von oberen und unteren Grenzen und ist insgesamt prägnanter und lesbarer.

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

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

Dieses Prinzip erstreckt sich auf die nicht-CSS-Verwendung von Media Queries, wie dasmedia Attribut von<link> Elementen oderwindow.matchMedia().

Wenn Sie alternative Stile haben, die durch Mediaschwellen ausgewählt werden, seien Sie besonders vorsichtig mit Ihren Media Queries. Denken Sie daran, dasswidth undheight gebrochene Werte sein können; stellen Sie sicher, dass bei jedem Wert ein und nur ein alternativer Stil wirksam ist.

Medienabfragen für mobile Geräte zuerst

In einem Stylesheet, dasMedienabfrage Stile für unterschiedliche Zielbildschirmgrößen enthält, schließen Sie zuerst die Gestaltungen für enge Bildschirme/mobile Ausstattung ein, bevor andere Medienabfragen getroffen werden. Fügen Sie die Gestaltung für größere Bildschirmgrößen über aufeinanderfolgende Medienabfragen hinzu. Die Einhaltung dieser Regel hat viele Vorteile, die inResponsive Design erklärt 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 */}

Zeichenketten

Wo immer Anführungszeichen im CSS-Syntax optional sind, verwenden Sie sie und verwenden Sie doppelte Anführungszeichen. Machen Sie es so:

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

Machen Sie nicht das Folgende, weil die Arten von erlaubten Zeichen eingeschränkter sind und manchmal zu subtilen Syntaxfehlern führen:

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

Mit der@import Regel spezifizieren Sie den Modulpfad als Zeichenkette, nicht alsurl().

@import "style.css";

@import url("style.css");

Siehe auch

CSS-Referenzindex - gehen Sie unsere CSS-Eigenschaften-Referenzseiten durch, um einige gute, prägnante, bedeutungsvolle CSS-Snippets zu überprüfen. Unsere interaktiven Beispiele im Abschnitt "Probieren Sie es aus" sind im Allgemeinen geschrieben, um den auf dieser Seite beschriebenen Richtlinien zu folgen.