Ga naar hoofdinhoud

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.

Doen

Gebruik component tokens voor de design beslissingen die per huisstijl verschillen.

.example-button {
  background-color: var(--example-button-background-color);
}

Doen

Gebruik basis tokens voor de design beslissingen in een custom.css of componenten die niet in het design system zitten.

.example-custom-footer {
  background-color: var(--basis-color-accent-1-inverse-bg-document);
  color: var(--basis-color-accent-1-inverse-color-default);
}

Doen

Gebruik basis tokens als fallback voor de design beslissingen in componenten die nog niet in de community zitten.

.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));
}

Niet doen

Hardcoded waardes voor design beslissingen

.example-custom-footer {
  background-color: #663399;
}

Niet doen

Huisstijl tokens van jouw organisatie in de component

.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.

Doen

Gebruik brand tokens in je thema

Daarin verwijst de component design token naar de brand design token

/* 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.

Doen

Huisstijl inladen met een eigen class name

<html class="utrecht-root example-theme">
<!-- 
  Example use of Community, Candidate and custom components
  that will be styled by the example-theme stylesheet
-->
  <body class="utrecht-body">
    <h1 class="nl-heading nl-heading--level-1">Example page</h1>
    <div class="example-card-group">
      <div class="example-card">
        <h2 class="example-card__heading nl-heading nl-heading--level-2">Hello</h2>
        <p class="nl-paragraph">Some content here</p>
      </div>
    </div>
  </body>
</html>

Niet doen

Huisstijl inladen in de :root

Zo kunnen andere stylesheets niet makkelijk worden ingeladen zonder mogelijke side-effects

: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.

Doen

Gebruik de prefix van de organisatie die de componenten beheert

/* 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;
}

Doen

Eigen prefix voor nieuwe componenten

Alle namen in gedeelde CSS beginnen met een prefix die uniek is voor de organisatie. De prefix bestaat uitsluitend uit letters en cijfers, zonder koppelstreepjes of andere tekens.

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

Doen

Eigen prefix voor specifieke component tokens bij gebruik van andere componenten

.example-video__button {
  --nl-button-background-color: var(--example-video-button-background-color);
  --nl-button-color: var(--example-video-button-color);
}

Niet doen

Eigen CSS om de tokens of CSS van een andere prefix te voorzien

/* 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.

Doen

Reset CSS in de component zelf

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.

Niet doen

Globale CSS reset

* {
  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.

Doen

Reset in een mixin

Om te voorkomen dat de code later als dode code wordt verwijderd, staat reset-code in een eigen mixin

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


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