import { Guideline } from “@site/src/components/Guideline”;

CSS conventie

Dit document beschrijft de conventies voor het schrijven van herbruikbare CSS voor componenten en applicaties met NL Design System. Deze zijn bedoeld voor iedereen die nieuwe componenten ontwikkelt of bijdraagt aan gedeelde CSS-bibliotheken en voor iedereen die aanvullende CSS scrhijft in een herbruikbare applicatie.

Huisstijl onafhankelijk

Schrijf CSS die ook werkt voor anderen. Herbruikbare CSS gebruikt geen huisstijlcode. CSS-variabelen worden gebruikt voor component design tokens die ingevuld kunnen worden met de huisstijl van een organisatie. Dit is van belang wanneer componenten door anderen worden gebruikt, of wanneer software door meerdere organisaties met hun eigen huisstijl wordt geïnstalleerd, zoals een CMS voor gemeenten of Common Ground-software.

```css .example-button { background-color: var(--example-button-background-color); } ``` ```css .example-custom-footer { background-color: var(--basis-color-accent-1-inverse-bg-document); color: var(--basis-color-accent-1-inverse-color-default); } ``` ```css .example-custom-footer { background-color: var(--example-custom-footer-background-color, var(--basis-color-accent-1-inverse-bg-document)); color: var(--example-custom-footer-color, var(--basis-color-accent-1-inverse-color-default)); } ``` ```css .example-custom-footer { background-color: #663399; } ``` ```css .example-custom-footer { background-color: var(--purple); } ```

Geïsoleerde theming

Zorg dat de CSS van een thema niet de stylesheet van anderen in de weg zit. De huisstijlcode staat voor iedere organisatie in een apart thema-bestand. Gedeelde CSS wordt aangeboden zonder side-effects. De CSS heeft pas effect op een pagina nadat een expliciete CSS-class is toegepast. Zo kan hergebruik plaatsvinden zonder onbedoelde invloed op bestaande stylesheets.

```css /* Voorbeeld thema in CSS op basis van de Design Tokens JSON */ .example-theme { --example-purple: #663399; --example-button-background-color: var(--example-purple); } ```

Dit thema-bestand kan automatisch worden gegenereerd via een Design Tokens JSON-bestand met Style Dictionary. Elke huisstijl kan een eigen design token JSON-bestand hebben dat in meerdere projecten wordt gebruikt.

```html

Example page

Hello

Some content here

``` ```css :root { --example-link-color: rebeccapurple; } ```

Herleidbare prefix

Zorg dat de prefix van de componenten en tokens herkenbaar en herleidbaar is. De componenten bij NL Design System worden bijgedragen door diverse organisaties. Om te herleiden waar een component vandaan komt en met wie je kan samenwerken om een verbetering door te voeren houden we de prefix van die organisatie aan. Ook in de applicatie van een organisatie met een andere naam. Het kan dus voorkomen dat een thema bestaat uit design tokens van diverse organisaties.

```css /* Voorbeeld CSS Output van de Design Tokens JSON met diverse componenten */ .example theme { --ams-breadcrumb-link-color: blue; --nl-link-color: blue; --utrecht-button-background-color: rebeccapurple; } ```

.example-video {
  border-color: var(--example-video-border-color);
  border-radius: var(--example-video-border-radius);
  border-width: var(--example-video-border-width);
}

```css .example-video__button { --nl-button-background-color: var(--example-video-button-background-color); --nl-button-color: var(--example-video-button-color); } ``` ```css /* Voorbeeld CSS Output van de Design Tokens JSON met diverse componenten */ .example theme { --example-breadcrumb-link-color: blue; --example-link-color: blue; --example-button-background-color: rebeccapurple; } /* Voorbeeld pseudo CSS om onnodig eigen componenten logica te onderhouden */ .example-breadcrumb { --ams-breadcrumb-link-color: var(--example-breadcrumb-link-color); @include ams-breadcrumb; } ```

Herbruikbare mixins

Schrijf SCSS mixins voor gebruik met andere CSS selectors. CSS-onderdelen worden aangeboden als SCSS-mixin, zodat andere projecten dezelfde stijlen kunnen toepassen op afwijkende selectors.

_mixin.scss:

@mixin example-link {
  color: var(--example-link-color);
}

index.scss:

@import "./mixin";

.example-link {
  @include example-link;
}

Een project dat geen invloed heeft op de HTML past de mixin toe op alle links:

@import "@example/css-components/link";

a:link {
  @include example-link;
}

Een project met Shadow DOM:

@import "@example/css-components/link";

:host {
  @include example-link;
}

Een project dat de mixin tijdelijk gebruikt tijdens een migratie van oude class names:

@import "@example/css-components/link";

.old-link {
  @include example-link;
}

Robuuste reset

Schrijf robuuste CSS die niet afhankelijk is van een algemene reset.css. Wanneer een HTML-element zoals <ul> wordt gebruikt voor een navigatiecomponent, worden browser-standaardstijlen — zoals padding-inline-start in Firefox of Safari — expliciet gereset.

```css ul.example-nav { padding-inline-start: 0; /* …other styles… */ } ```

Ook als het project een reset.css-variant gebruikt, blijft deze reset aanwezig in de componentcode zodat het ook werkt voor projecten zonder die reset.css.

```css * { padding: 0; } ```

Reset in een SCSS mixin

Wanneer een property is ingesteld op de initial value (zoals 0 voor padding), kan dit eruitzien als overbodige code. Als reset-code in een losse mixin staat, ontbreekt de context dat het bedoeld is als browser-reset.

@mixin reset-ul {
  padding-inline-start: 0;
  /* …other styles… */
}

@mixin example-nav {
  @include reset-ul;
  /* …other styles… */
}