Anleitungen

Aufgabenbezogene Schritt-für-Schritt-Beispiele, alle live auf dieser Seite nachvollziehbar. Für die reine Token-/Klassen-Referenz siehe das Handbuch.

1. Eigenen Abschnitt bauen

Für eigene Seiten reichen meist drei Bausteine: ein .ncss-container für die Spaltenbreite, .ncss-stack für vertikalen Rhythmus zwischen den Kindern, und bei Bedarf eine .ncss-py-*-Klasse für zusätzliches Innen-Padding oben/unten.

<section class="ncss-container ncss-stack ncss-py-lg">
  <h2>Titel</h2>
  <p>Text ...</p>
  <button class="ncss-btn ncss-btn--primary">Aktion</button>
</section>

Ergebnis (live, dieselben Klassen):

.ncss-stack setzt gap: var(--ncss-space-md) zwischen ALLEN direkten Kindern - kein manuelles Margin pro Element nötig. Für engeren/weiteren Abstand .ncss-stack--tight/--loose statt einer neuen Zahl zu erfinden.

2. Abstände: drei Ebenen, je nach Bedarf

Bevor eine neue Utility-Klasse oder gar eine Magic Number infrage kommt, in dieser Reihenfolge prüfen:

1. Nichts tun. base.css gibt Absätzen/Überschriften/Listen etc. bereits einen sinnvollen margin-block-end - der Normalfall braucht gar keine Klasse.
2. Utility-Klasse. .ncss-py-*/.ncss-px-*/.ncss-mb-*/.ncss-gap-* (helpers/layout.css, je vier Stufen sm/md/lg/xl) decken die meisten Fälle ab.
3. Token direkt, als letzter Ausweg. Für eine Kombination, die es als Klasse nicht gibt: style="padding-inline-start: var(--ncss-space-2xl)" ist in Ordnung - es ist ein TOKEN, keine Magic Number. Was NICHT in Ordnung ist: style="padding: 17px".

Alle drei Ebenen nutzen dieselben --ncss-space-*-Tokens - die sind bereits fließend (clamp()), also automatisch "responsiv" ohne Breakpoints: derselbe Abstand skaliert stufenlos zwischen einer Mindest- und einer Maximal-Viewportbreite. Fenster ziehen, um es zu sehen:

3. Responsives Grid ohne Breakpoints

.ncss-grid ist ein intrinsisches Grid (repeat(auto-fit, minmax(var(--ncss-grid-min), 1fr))) - es zählt Spalten anhand der verfügbaren Breite, nicht anhand fester Breakpoints. Reagiert automatisch auf den CONTAINER (nicht nur den Viewport), funktioniert also auch in einer schmalen Sidebar korrekt.

<div class="ncss-grid" style="--ncss-grid-min: 10rem;">
  <div>Karte 1</div>
  <div>Karte 2</div>
  <div>Karte 3</div>
  <div>Karte 4</div>
</div>

Live - Box unten rechts in der Breite ziehen, keine Media Query im Spiel:

--ncss-grid-min ist eine Custom-Property-Parametrisierung, kein Deko-Inline-Style (siehe Konventionen im Handbuch) - je höher der Wert, desto früher fällt eine Spalte weg.

4. Wenn wirklich ein Breakpoint-Sprung nötig ist

Nicht jeder Fall ist ein Fließen - manchmal soll sich an einer FESTEN Breite etwas grundsätzlich ändern (z.B. Navigation klappt von Hamburger auf Vollmenü um). Dafür die dokumentierte Breakpoint-Konvention aus tokens.css nutzen, in einer eigenen @media-Regel:

.mein-element {
  background-color: var(--ncss-color-danger-100);
}
/* -- ncss breakpoint: md (768px) -- */
@media (min-width: 48rem) {
  .mein-element {
    background-color: var(--ncss-color-success-100);
  }
}

Live - das BROWSERFENSTER schmaler/breiter als 768px ziehen (echte Media Query, keine Container Query, deshalb reagiert eine Innenbox hier nicht):

Wichtig: var() funktioniert aktuell in KEINEM Browser innerhalb der @media-Bedingung selbst (@media (min-width: var(--x)) ist ungültig) - die Zahl (48rem) muss dort direkt stehen. Der Kommentar -- ncss breakpoint: md -- davor hält fest, dass sie der dokumentierten Konvention folgt, statt eine neue Zahl zu erfinden.

5. Fokuspunkt bei zugeschnittenen Bildern setzen

Überall wo NativeCSS object-fit: cover nutzt (Ratio-Helpers, Card-Media, Video), steuert --ncss-focus-point (Default center) den Bildausschnitt:

<div class="ncss-ratio-square" style="--ncss-focus-point: 20% 80%;">
  <img src="foto.jpg" alt="...">
</div>

Ausführliches, live vergleichbares Beispiel: media.html#bilder.

6. Eigene Komponente anlegen

1. Neue Datei unter components/, z.B. components/meine-komponente.css.
2. Ausschließlich var(--ncss-*) verwenden - kein hartcodierter Wert. Fehlt ein Token, erst in tokens.css/colors.css ergänzen.
3. In ncss.css importieren, im Layer components: @import url("components/meine-komponente.css") layer(components);
4. Mit Playwright im echten Browser verifizieren - insbesondere Dark Mode (Kontrast!).

Reales Beispiel zum Nachlesen: components/sparkline.css (klein, in sich abgeschlossen, gute Vorlage für den Umfang, den eine einzelne Komponente haben sollte).

7. Neue Web-Awesome-Komponente farblich einbinden

1. Lokale Referenz-Doku ZUERST lesen: vendor/webawesome/dist-cdn/skills/webawesome/references/components/<name>.md - zuverlässiger als die öffentliche Doku-Seite (siehe Handbuch, Fallstrick 0).
2. Prüfen, welche --wa-color-*/--wa-*-Variablen die Komponente tatsächlich nutzt.
3. In webawesome-bridge.css ergänzen, ausschließlich auf ncss-Tokens verweisend - keine eigenen Werte.
4. Component-Tag einmal ins Markup setzen, Autoloader lädt den Rest automatisch nach - kein manueller Import nötig.
5. In BEIDEN Themes mit Playwright verifizieren (siehe Handbuch, Fallstrick 2 - die häufigste Bridge-Fehlerquelle ist Dark-Mode-Kontrast).