Belofte maakt schuld
Op de documentatiepagina van onze tooltip stond een codevoorbeeld. Het gaf de tekst mee als content, en die eigenschap bestaat niet. Wie het kopieerde kreeg een lege tooltip.
Naast dat voorbeeld stond een werkende demo van hetzelfde component. Twee weergaves op één pagina die het oneens waren, maandenlang, zonder één signaal.
Een design system doet beloftes. Over gedrag, over toegankelijkheid, over hoe je iets hoort te gebruiken. Belofte maakt schuld, en als niemand die belofte nameet komt de schuld ergens anders terecht: bij de afnemer, die er niets aan kon doen.
De bron van waarheid is verschoven
Een design system woonde tot voor kort in het ontwerpgereedschap. Een bibliotheek in Figma, een documentatiesite die beschreef wat erin zat, en code die daar een vertaling van was. Het ontwerp was het origineel.
Dat is omgedraaid. Bij ons is de tokenset één JSON-bestand waar de CSS uit gegenereerd wordt, staan de componenten in code, en is het ontwerpgereedschap een afnemer geworden in plaats van de bron. Dat is geen Simplor-eigenaardigheid; het is waar het vak heen beweegt.
Die verschuiving heeft een gevolg dat weinig besproken wordt. Documentatie is daarmee een derde artefact geworden dat een bron moet bijhouden die sneller beweegt dan zij. Vroeger beschreef je een bibliotheek die per kwartaal veranderde. Nu beschrijf je code die dagelijks verandert, en de beschrijving heeft geen enkele koppeling met wat ze beschrijft.
Waarom die documentatie nooit af is
Neem eenentwintig componenten. Elk met varianten, maten, staten, twee thema’s en twee leveringsvormen. In proza beschrijf je dan duizenden combinaties, en je beschrijft ze één keer, op de dag dat je ze opschrijft.
Volledigheid is daarmee onbereikbaar en actualiteit is een kwestie van discipline die niemand een jaar volhoudt. Erger is dat verval geen signaal geeft. Er komt geen foutmelding als een zin niet meer klopt, want er is geen fout: er is alleen een bewering die achterloopt.
En er is een menselijke reden dat het niet gemeld wordt. Wie een onjuiste belofte tegenkomt, bouwt er stilletjes omheen. Deadline, omweg, klaar. Het is niet zijn component. Zo veroudert een design system van binnenuit terwijl alle tests groen staan.
Het probleem is dus niet dat die documentatie slecht geschreven is. Het probleem is dat er niets onder staat. Een belofte hoort een bewering te zijn met een test eronder, en zonder die test is het een mening met een datum erop.
Van beschrijving naar contract
Een design system dat als product wordt beheerd doet beloftes aan zijn afnemers. Dat is de hele reden dat mensen erop bouwen zonder alles zelf na te lopen. En een product dat beloftes doet, moet ze kunnen waarmaken.
Wij zijn onze documentatie daarom gaan behandelen als een contract. Niet mooier opgeschreven, maar zo opgeschreven dat een machine er iets van kan vinden.
| Wat er misgaat | Zonder contract | Met contract |
|---|---|---|
| Een belofte klopt niet meer | Niets. Er is geen fout, alleen een zin die achterloopt | De testrun wordt rood |
| Een variant verdwijnt uit een voorbeeld | Je meet minder en niemand merkt het | De dekkingstest wijst hem aan |
| Iemand kiest het verkeerde component | Hopen dat een reviewer het ziet | De afdwingbare regels wijzen het aan |
| Er komt een component bij | De documentatie loopt achter | Hij komt er niet in zonder contract |
Vier velden per component. Het derde is bekend, het tweede en het vierde veel minder.
requires
Wat er moet zijn om geldig te zijn. Zichtbare tekst in een badge, minstens één optie in een keuzelijst, een legenda boven een radiogroep.
provides
De taak die het vervult, als term waar iets op kan kiezen. Niet 'dropdown' maar 'één keuze uit een bekende verzameling'.
guarantees
Wat het belooft, en per belofte de test die hem bewijst. Een verwijzing naar een test die niet bestaat wordt geweigerd.
constraints
Waar dit component het verkeerde antwoord is. Een badge is geen categoriekleur. Een checkbox is geen schakelaar.
Eenentwintig componenten, honderddrieëntwintig verwijzingen naar tests, en een controle die meedraait bij elke testrun. Het contract van de badge staat op de componentpagina, naast de demo en de code.
Het verschil met documentatie is niet de opmaak maar de richting: een contract kan weigeren. Een garantie zonder test komt er niet in, een component zonder contract komt er niet bij, en tien van de regels draaien als controle over de site die het systeem gebruikt.
Wat dat opleverde
Zeven bevindingen, geen daarvan gevonden door beter te kijken. De vier die het meest zeggen:
- De tooltip had geen naam. Niet alleen het voorbeeld was fout; het component kondigde zich bij een schermlezer aan zonder te kunnen zeggen wat erin stond.
- Vijf componenten werden helemaal niet gemeten. Ze bestaan in twee leveringsvormen en één daarvan zat niet in de toegankelijkheidsmeting. Niemand wist het, want een ontbrekende meting geeft geen rood.
- Zeven varianten stonden in geen enkel voorbeeld, en werden dus nergens gemeten. Eén ervan haalde de contrastnorm niet.
- Een badge haalde 4,45 waar 4,5 moet. Dat is de contrastverhouding tussen de labeltekst en waar hij op staat, en 4,5 is de ondergrens die WCAG AA stelt voor gewone tekst. Vijf honderdsten eronder is geen bijna: het is een norm die je niet haalt. De kleur was ooit afgestemd tegen de achtergrond van de documentatiekaart in plaats van tegen de paginakleur.
Daar zit een les in die verder gaat dan design systems. Een set voorbeelden kan stilletjes krimpen. Haal een variant weg en je meting blijft groen, want er is minder om te meten. Het aantal groene tests beweegt niet, dus niets wijst het aan. Dat is de ergste soort regressie: hij ziet er identiek uit aan vooruitgang.
De andere kant van het contract
Tot hier ging het over één kant: doet het systeem wat het belooft. De andere kant is of de afnemer zich aan de afspraak houdt, en die wordt vrijwel nooit gemeten.
Adoptie wordt normaal geteld. Hoeveel componenten uit het systeem, en welk deel van alles wat het had kunnen dekken. Dat is een aantal en een verhouding, en geen van beide zegt iets over de kwaliteit van het gebruik. Een badge die twaalf categorieën uit elkaar probeert te houden telt gewoon mee als adoptie, haalt de contrastnorm, en is toch het verkeerde component.
Daarom draaien de afdwingbare regels uit onze contracten nu als controle over alles wat het systeem afneemt: de publieke site én het klantportaal. Dat portaal telt het zwaarst, want daar zitten de formulieren, de tabellen en de bevestigingen die echt iets doen, en daar is verkeerd gebruik dus ook het duurst. Het systeem stelt de regel, de afnemer toetst zichzelf, want een pakket kan niet zien wie het importeert.
Dat is adoptie op de kwaliteitsas in plaats van op aantallen. Hoe je die aantallen meet staat in adoptie van je design system meten. Dit is de vraag die daarna komt.
Waarom provides en constraints vandaag meer opleveren dan vijf jaar geleden
Een groeiend deel van de code wordt geschreven met een agent ernaast. Dat verandert wie je documentatie leest, en die lezer gedraagt zich anders.
Een mens bouwt om een onjuiste belofte heen. Een agent neemt hem aan. Ons tooltipvoorbeeld kostte een mens een halve dag; een agent produceert er werk mee dat overtuigend leest, in een tempo waarin niemand elk voorbeeld naloopt.
Kiezen gaat ook anders. Een mens kiest een component door de galerij te bekijken; een agent kiest door te lezen. Op “dropdown” valt niets te kiezen. En een agent heeft geen aarzeling: niets in een typedefinitie zegt dat een badge geen categoriekleur is, dus dat moet ergens staan waar het gelezen wordt.
Dit is geen betoog dat je systeem AI-klaar moet zijn. Het is de constatering dat de prijs van onbewezen documentatie is gestegen, en dat de verschuiving die al gaande was daardoor sneller gaat.
Wat het kost, en waar je begint
Eerlijk over de prijs: nieuwe componenten toevoegen gaat langzamer, want de testrun weigert er een zonder contract. Beloftes die je niet kunt bewijzen mag je niet opschrijven. En op de dag dat je begint blijkt je systeem slechter dan je dacht.
Van onze honderdacht regels zijn er tien machinaal te toetsen. Dat klinkt mager en het is het nuttigste getal uit het traject: nu is duidelijk welke een regel zijn en welke een reviewvraag. Daarvoor lazen ze allemaal even hard.
Beginnen doe je niet bij het formaat maar bij de beloftes die je al toetst. Vrijwel elk systeem heeft ergens een toegankelijkheidscontrole en een paar gedragstests staan. Schrijf per component op welke belofte daarbij hoort en verwijs ernaar. Dat kost een middag en levert een eerlijke ondergrens op.
De tweede stap is de scherpe: zet er een controle op die weigert wanneer een verwijzing niet klopt. Zonder die stap is een verwijzing een string, en strings verouderen precies zo stil als de proza die je net vervangen hebt.
Doe je geen van beide, dan blijft je systeem beloftes doen die niemand nakijkt, en blijven afnemers ze gebruiken zoals het uitkomt. Belofte maakt schuld, en die schuld heeft in dit vak een naam. Alleen staat hij dan niet in je code maar in je documentatie, en betaalt iemand anders hem af.
Of wat je hebt eigenlijk een systeem is of een verzameling code, staat in design system of componentenbibliotheek. Waarom systemen vastlopen zonder eigenaarschap, in waarom design systems stranden na de lancering. Hoe wij design systems bouwen en beoordelen, inclusief de vraag of de beloftes die ze doen ook nagemeten worden.