Documentatie: Changelogs voor designers

[Robbert]

Specificatie

• Misschien kan de template in de documentatie staan als codeblock
• Misschien kan de template in een .changesets/major.md.template staan, met wat inline uitleg over de change ✅
• Uitzoeken: Gaan comments in een changeset markdown mee met de changelog? Indien niet, dan kunnen we comments in de template plaatsen ❌ .

Acceptatie-criteria

• Er is documentatie op nldesignsystem.nl onder de "Handboek" ➝ Designers categorie
• Uitleg over breaking changes voor design tokens naamgeving
• Is een design beslissing wijzigen een breaking change, of een feature?
• Tip: geef informatie hoe designers kunnen migreren, bijvoorbeeld: token X is nu token Y geworden, rename
• Tip geven over backwards compatibility van een theme. Bijvoorbeeld: example.button.icon.space wordt example.button.column-gap. Dan kun je dit maken:

{
  example: {
    button: {
      'column-gap': { value: '8px' },
      icon: {
        space: { value: '{example.button.column-gap}' },
      },
    },
  },
}

• Uitleg dat de versie niet automatisch wordt gepubliceerd, je moet nog de automatisch aangemaakte PR nog mergen.
• Uitleg wat het effect is als oude software een nieuwe theme gebruikt terwijl er breaking changes zijn. Bijvoorbeeld: de button verliest de ontworpen icon space, die krijgt de default waarde voor de icon space (als die er is)
• We bieden een template .md aan voor major, minor en patch changes.
• Designers moeten kunnen weten welke npm package ze gebruiken.
• README.md in .changesets/ van themes repo met in elk geval een linkje naar de documentatie op de website
• Met de designers even een plan maken voor specifieke aanwijzingen voor wijzigen van brand tokens en common tokens.
  • Common tokens en brand tokens worden in de praktijk vaak gebruikt door front-end developers in de CSS, voor custom CSS. Bijvoorbeeld, om een margin in een bepaalde situatie in te stellen. Daarom is het handig om als migratie-stap aan te bieden dat front-end developers bepaalde CSS variables moeten renamen. Bijvoorbeeld: "vervang de volgende tokens: var(--example-space-block-elephant) ➝ var(--example-space-block-xl2).
• Misschien ook leuk: een screenshot van GitHub code search voor design tokens.
  • Bijvoorbeeld: --utrecht-badge-counter-color hernoemen naar --utrecht-number-badge-color: https://github.com/search?q=--utrecht-badge-counter-color&type=code

Testen

• @jeffreylauwers en @Rozerinay hebben het document toegepast om een changelog entry te maken in de themes repository, en ze zijn tevreden!