Arkitektur for et designsystem uten rammeverk

Et tekstfelt med ledetekst, hjelpetekst og feilmelding er HTML og ARIA, og har vært det lenger enn noe rammeverk i bruk i dag. Likevel krever det i dag et rammeverk du ikke kan bytte ut, og en omskriving hver gang rammeverket skifter retning.

Dette er syv krav et designsystem må oppfylle for å slippe det. For hvert av dem: hva det går ut på og hva det koster. Ingen av dem er gratis, og prisen står nederst på lysbildene.

Alt hviler på denne ene setningen:

Det gjennomgående eksempelet er Fristil, et designsystem bygget etter disse kravene og publisert på fristil.sobernetics.no og på npm som @fristil/designsystem.

Kort fortalt

Rammeverk kommer og går. Et designsystem som er bundet til ett av dem, må skrives om hver gang rammeverket skifter retning. Skal det stå igjen når appene rundt byttes ut, må det bygge på det nettleseren allerede forstår.

1. Nettleseren er plattformen. Komponentene er CSS-klasser og web components, og virker likt i React, i Astro, i ren HTML og med en server skrevet i Kotlin.
2. Den som rendrer, eier markupen. Den som rendrer, med CSR eller SSR, skriver klasser og koblinger, og komponenten tar seg av tastatur, fokus og posisjonering. De to overlapper ikke.
3. Tilgjengeligheten skrives ett sted. Den samme funksjonen regner ut koblingene, enten den kalles der markupen rendres, eller av komponenten i nettleseren.
4. DOM-en er fasiten. Komponenten leser tilstanden fra markupen, og har ingen egen kopi av den.
5. Typene virker uten rammeverk. Byggefunksjonene er vanlige TypeScript-funksjoner, og editoren kjenner valgene.
6. Konsumentens CSS vinner. En vanlig regel skrevet av teamet slår systemets, uten !important.
7. Teamet kan ta over koden. Én komponent kan kopieres inn i prosjektet den dagen systemet ikke strekker til.

Arbeidet forsvinner ikke. Det flyttes til dem som lager systemet: tester i tre nettlesermotorer, venting på den siste nettlesermotoren som mangler en funksjon, og klassenavn som ikke kan endres fordi de står i koden til andre.

Nederst på lysbildene står inntil tre linjer: hva kravet betyr for teamene som bruker systemet, hva det koster dem som forvalter det, og hvordan Fristil har løst det.

Syv krav

Resten av presentasjonen tar ett krav om gangen. Det første gjør de andre mulige, og det siste gjør at du kan forlate systemet når du vil. Til slutt kommer fellene, og så Fristil i bruk: et skjemafelt og et spill som viser at arkitekturen virker.

1. Nettleseren er plattformen5 lysbilder
2. Den som rendrer, eier markupen6 lysbilder
3. Tilgjengeligheten skrives ett sted1 lysbilde
4. DOM-en er fasiten3 lysbilder
5. Typene virker uten rammeverk2 lysbilder
6. Konsumentens CSS vinner1 lysbilde
7. Teamet kan ta over koden1 lysbilde
8. Fellene3 lysbilder

Krav 1 av 7 · Nettleseren er plattformen

Hvorfor plattformen først, og ikke React først

Grunnen til ikke å bygge på React er ikke at noe annet er bedre i dag. Grunnen er at appene rundt systemet kommer til å byttes ut, og systemet skal stå igjen.

• Levetiden er ulik. React har gått fra klasser via hooks til serverkomponenter på ti år, og hvert skifte traff alle som bygde på det. En CSS-klasse fra ti år siden virker fortsatt uendret, og det gjør en web component skrevet etter Custom Elements v1 også.
• Det går bare én vei. Av komponenter bygget på plattformen kan hvem som helst lage en React-pakke senere. Av et React-bibliotek kan ingen lage en HTML-versjon.
• Porteføljen spenner over mange rammeverk samtidig. Nye apper i React, ti år gamle apper i noe annet, og publiseringsløsninger som bare sender HTML. Et designsystem bundet til ett rammeverk når bare den delen som bruker det.
• Utseendet krever ingen kjøretid. En knapp, et merke og et kort er CSS. Blir de React-komponenter, må rammeverket lastes inn og kjøre før de ser riktige ut.

Krav 1 av 7 · Nettleseren er plattformen

Hva nettleseren gjør selv

Det meste av det som er vanskelig i et designsystem, er allerede løst i nettleseren. Bygger systemet på nettleseren, er det kode ingen trenger å vedlikeholde.

Det som gjenstår, er koblingen mellom delene, tastaturstyringen der nettleseren ikke har en ferdig kontroll, og et enhetlig utseende. Det er en langt mindre jobb enn å bygge fokus, lag og skjemaer selv.

Krav 1 av 7 · Nettleseren er plattformen

Prisen for å bygge på nettleseren selv

Uavhengigheten er ikke gratis. Den er betalt et annet sted: av dem som lager systemet, ikke av teamene som bruker det.

appearance: base-select
Chromium 148 ✓  WebKit 26.4 ✓
Firefox 150     ✗

Krav 1 av 7 · Nettleseren er plattformen

Hva det koster appen din

Et designsystem stiller krav til appen som tar det i bruk. Dette er kravene Fristil stiller, og til sammenligning kravene et React-basert designsystem stiller, hentet fra peerDependencies i @skatteetaten/ds-forms 3.0.0:

For å bruke skjemakomponentene i det systemet må appen din ha tolv pakker: React 19, i18next, react-i18next, date-fns og åtte pakker fra systemet selv. Fristil krever ingen, og hvilket rammeverk appen bruker, spiller ingen rolle.

Dette er ingen kritikk. Et React-basert system er et rimelig valg når alt er React. Spørsmålet er hva det koster dem som ikke bruker React.

Én knapp på skjermen, i en tom app. Bygget med esbuild, gzippet.

Av de 119 kilobytene er 67 React selv. Har du React fra før, legger det systemet til rundt 51 kB for den ene knappen. Byggefunksjonen fs med typer koster 3,9 kB i tillegg i Fristil.

Pakken har ingen avhengigheter, og ingenting i den gjør noe bare ved å bli importert. Hver modul kan lastes på en server uten DOM, så import { fs } virker med serverrendring.

Krav 2 av 7 · Den som rendrer, eier markupen

Tre måter å rendre på

Et designsystem må virke uansett hvor markupen rendres. Det finnes tre tilfeller, og de fleste team jobber med det første.

const svar = await fetch("/api/treff")
setTreff(await svar.json())

Krav 2 av 7 · Den som rendrer, eier markupen

Det strengeste tilfellet: SSR med morfing

Med SSR bygges HTML-en på serveren. Når siden oppdateres, sender serveren den biten av HTML-en på nytt, og et bibliotek fletter den inn i siden. Det kalles morfing, på engelsk DOM morphing. Nedenfor står de to linjene i Datastar som gjør det, og de er grunnen til at systemet er bygget som det er.

// r = elementet i siden nå, s = det serveren sendte,
// o = navnene i data-preserve-attr. Like før er s kopiert inn i r.
for (let {name: l} of Array.from(r.attributes))
  !s.hasAttribute(l) && !o.includes(l) && r.removeAttribute(l)

// Står attributtet der, men ikke i det serveren sendte,
// så fjern det. Med mindre malen har fredet navnet.

Nødutgangen er data-preserve-attr, som HTML-malen på serveren må fylle med navnene på alt komponenten har satt. Endres det komponenten setter, må hver mal endres i takt, uten at noen kompilator sier fra. Et designsystem kan derfor ikke bygge på den.

Har en komponent lagt til aria-describedby i nettleseren, er det borte ved neste oppdatering, og skjermleseren mister koblingen uten at noe sier fra. React har det samme i en annen form: rendres foreldrekomponenten på nytt, kan noder en web component har lagt inn, bli kastet bort. Derfor:

Datastar er det strengeste av de tre, og det som virker der, virker også i TanStack Start og React Server Components. Kravet nevner likevel ikke noe rammeverk: det komponenten har satt, skal overleve at attributter blir fjernet.

Krav 2 av 7 · Den som rendrer, eier markupen

De to lagene

Regelen på forrige lysbilde deler systemet i to lag: det som rendres, og det komponenten gjør etterpå. Delingen er nødvendig fordi en ny rendring kan rive bort attributter og noder komponenten har lagt til, mens hendelseslyttere blir stående. De to lagene overlapper derfor ikke: en byggefunksjon setter aldri en hendelseslytter, og en komponent setter aldri et attributt på noe serveren eier.

Ingen shadow DOM. Shadow DOM er grunnen til at mange har prøvd web components og gitt opp: et felt i en shadow root står utenfor skjemaet rundt, og du må melde verdien inn fra verten med ElementInternals for å få den med i innsendingen. Her skriver du <input> selv, i vanlig DOM, og komponenten legger seg rundt.

Krav 2 av 7 · Den som rendrer, eier markupen

Tre kategorier, og ett spørsmål

Med SSR skriver serveren all HTML, og med CSR gjør rammeverket det. Hvilken kategori en komponent hører til, handler derfor ikke om hvem som skriver HTML-en. Den handler om hvem som eier DOM-en mens siden lever.

<button class="fs-button"
  data-variant="secondary">

<fs-field>
  <label>…</label>
  <input class="fs-input">
</fs-field>

toast.show("Lagret")

Én setning avgjør hvor en komponent havner.

Krav 2 av 7 · Den som rendrer, eier markupen

To veier til den samme kontrakten

Det avgjørende er om koden som lager markupen, kan kalle en funksjon. Hvor den kjører, spiller ingen rolle.

const felt = fs.field({ id: useId(), help: true })

<div>
  <label {...felt.label}>E-post</label>
  <input {...felt.control} type="email" />
  <p {...felt.help}>Vi sender aldri spam</p>
</div>

// Koblingen står i markupen fra første rendring.
// Komponenten trengs ikke.

<fs-field>
  <label class="fs-label">E-post</label>
  <input class="fs-input" type="email">
  <p class="fs-help-text">Vi sender aldri spam</p>
</fs-field>

// Ingen id-er, ingen for, ingen aria-describedby.
// Komponenten setter koblingen i nettleseren.

De to er ikke et spørsmål om smak. De er to veier for to slags kode, og begge ender med den samme HTML-en hos brukeren.

Krav 2 av 7 · Den som rendrer, eier markupen

Det komponenten får skrive

Regelen sier at komponenten aldri legger til noe i markup andre har rendret. Likevel setter <fs-field> fra forrige lysbilde id, for og aria-describedby på slike elementer. Det henger sammen fordi alt komponenten skriver, er regnet ut fra det som ble rendret.

• Den leser før den skriver. Id-en hentes fra feltet eller fra ledetekstens for, og id-er som ble rendret i aria-describedby, blir med i svaret.
• Den sammenligner før den skriver. Står den samme verdien der fra før, skriver komponenten ingenting. Er hele koblingen rendret fra før, endrer komponenten ingenting.
• Den husker hva den selv skrev, og på hvilken node. Bare det kan den sette tilbake når en oppdatering river det bort. En id den har laget, kommer tilbake som den samme id-en.

FristilHjelperen all skriving går gjennom, forenklet

function setAttr(el, navn, verdi) {
  if (el.getAttribute(navn) !== verdi) el.setAttribute(navn, verdi)
}

Krav 3 av 7 · Tilgjengeligheten skrives ett sted

Én funksjon, to innganger

Koblingen mellom ledetekst, felt, hjelpetekst og feilmelding er den samme uansett hvem som skriver markupen. Derfor finnes den ett sted, og de to veiene er to kall til den samme funksjonen.

Fristilramme/field/field-core.ts

computeFieldAttributes(...)
   ├── fs.field()      ← kalles der markupen rendres
   └── <fs-field>      ← komponenten kaller den på elementer som står i DOM-en

Endres kontrakten, endres den der, ikke i komponenten. Det svarer også på spørsmålet som alltid kommer: Skal ikke hver server skrive dette selv? Den dagen hver server må gjøre det selv, er det et designsystem bare for JavaScript, med en manuell reserve for alle andre, og det er reserven som ryker først.

Krav 4 av 7 · DOM-en er fasiten

Når en ny rendring river bort det komponenten satte

En ny rendring kan fjerne det komponenten satte: morfingen stryker attributtet, og React kan bytte ut noden. Komponenten vet hva den selv har regnet ut og skriver det inn igjen med én gang. Den som rendrer, trenger derfor ikke vite noe om hva komponenten gjør:

<fs-field>
  <label class="fs-label">E-post</label>
  <input class="fs-input" type="email">
  <p class="fs-help-text">Vi sender aldri spam</p>
</fs-field>

<fs-field server-controlled>

Har komponenten regnet ut attributtet, kan den regne det ut på nytt. Har brukeren gjort noe, vet komponenten hva det var, for den var til stede da det skjedde. Det er det som gjør reparasjonen mulig.

Det flimrer ikke, og det er testet. Morfingen fjerner attributtet, observatøren setter det tilbake i samme mikrotask, og nettleseren rekker ikke å tegne imellom. Den rendrede utgaven står i DOM-en et øyeblikk uten at noen ser den.

Krav 4 av 7 · DOM-en er fasiten

Komponenten skal aldri regne ut det den kan lese

Den som rendrer, og komponenten ser på den samme siden. Holder komponenten sin egen utgave av noe som også rendres, finnes tilstanden to steder, og da er det bare et spørsmål om tid før de to blir uenige.

At et felt er ugyldig, står som aria-invalid på kontrollen. Leser komponenten det derfra, er den alltid enig med rendringen. Leser den i stedet sitt eget attributt på verten, vil den før eller siden fjerne noe som nettopp ble rendret. I React viser det seg som en hydreringsfeil, i Datastar som en feilmelding på et gyldig felt.

Hvilken fane som er valgt, leses derfor fra aria-selected og ikke fra et eget attributt. Når komponenten både leser og skriver et attributt, må den også vite hvem som satte det.

Uten det gir den samme markupen to ulike svar, alt etter hvilke tilstander verten har hatt før.

Krav 4 av 7 · DOM-en er fasiten

Komponenten sier fra når markupen ikke henger sammen

HTML har ingen kompilator. Skriver et team et felt uten ledetekst, er det ingenting som stopper det, og siden ser helt riktig ut.

Den som merker feilen, er den som ikke ser skjermen: feltet blir lest opp uten navn. En komponent som gir opp uten et ord, sender feilen videre til brukeren. Den skal i stedet skrive én linje i konsollen, mens utvikleren fortsatt sitter med koden.

<fs-field>
  <input class="fs-input" id="fodselsdato">
</fs-field>

fs-field: fant ingen <label>.
Feltet får da ingen ledetekst, og
en skjermleser leser det opp uten navn.

En advarsel som slår falsk alarm, blir ignorert innen en uke. Tre valg gjør at denne er til å stole på:

• Den venter til siden har falt til ro. HTML fra en server kommer i biter, og et rammeverk kan rendre i flere omganger, så et øyeblikk uten ledetekst er helt normalt. Komponenten ser etter en gang til og sier bare fra hvis det fortsatt er galt.
• Samme melding hver gang. Et tall i meldingen, som i «Fant 3 faner, men 1 panel», gjør den til en ny melding for hvert panel, og den ene advarselen blir til tjue.
• Den peker på den egentlige feilen. Sprettoppvinduet finner knappen sin ved å slå opp panelets id. Mangler id-en, skal meldingen si det, og ikke at knappen mangler. Ellers leter utvikleren på feil sted.

Krav 5 av 7 · Typene virker uten rammeverk

Ett objekt inn, attributter ut

Innvendingen mot å forlate React er som regel utvikleropplevelsen: du mister komponenter som kjenner sine egne valg. Svaret er at en byggefunksjon gir det samme, fordi den er en vanlig TypeScript-funksjon. Den returnerer attributter, og editoren kjenner dem.

fs.button({ variant: "secondary" })
// { class: "fs-button", "data-variant": "secondary" }

fs.input({ type: "email", state: "invalid" })
// { class: "fs-input", type: "email",
//   "data-state": "invalid", "aria-invalid": "true" }

Skriver du feil, for eksempel variant: "secondry", får du rød strek i editoren før du lagrer, overalt der TypeScript ser koden: i JSX, i Astro og i JavaScript med typesjekking slått på. Uten typesjekking kan du sjekke verdien ved kjøring med fs.button.isVariant().

Krav 5 av 7 · Typene virker uten rammeverk

Kodeagenter får en sjekk i hvert miljø

En kodeagent fyller hullene med det den har sett i andre designsystemer: fs-modal, data-variant="outline". Den stopper bare hvis noe sier fra mens den jobber.

// knapp.ts
fs.button({ variant: "outline" })

$ tsc
knapp.ts(2,34): error TS2322: Type '"outline"'
  is not assignable to type '"danger" | "primary"
  | "secondary" | "ghost" | undefined'.

$ npx @fristil/designsystem sjekk side.html
side.html:1:14: advarsel: Klassen «fs-modal»
  finnes ikke i Fristil.
side.html:2:29: advarsel: data-variant kan ikke
  være «outline» på button. Lovlige verdier:
  secondary, ghost, danger, og primary uten attributt.

2 funn i 1 fil.
$ echo $?
1

Krav 6 av 7 · Konsumentens CSS vinner

Laget som gjør det mulig

Et team som må skrive !important for å flytte en knapp fire piksler, slutter å bruke systemet. Derfor ligger all komponent-CSS i et eget lag, og en regel uten lag slår alt som står i ett.

.fs-button           (0,1,0)
.fs-button:disabled  (0,2,0)  ← systemets vinner

@layer fristil {
  .fs-button:disabled { … }
}
.fs-button { … }  ← usortert, vinner

padding: var(--fs-button-padding,
             var(--fs-spacing-2) var(--fs-spacing-4));

Krav 7 av 7 · Teamet kan ta over koden

Når systemet ikke strekker til

Et team som trenger noe systemet ikke har tenkt på, skal komme videre samme dag. Alternativet er at de kopierer komponenten inn i prosjektet for hånd. Da mister teamet og systemet kontakten med hverandre, og feilrettinger når ikke fram.

Det som gjør kopien brukbar, er at henvisningene ut av komponenten peker på pakken etterpå, og ikke på filer som ikke finnes hos teamet.

FristilKildekoden til én komponent, inn i prosjektet ditt

npx @fristil/designsystem overta button --ut=src/ui

Kommandoen skriver om henvisningene, slik at ../shared.js blir @fristil/designsystem/shared. Oppslaget bygges av exports i pakken, slik at det som kopieres, faktisk virker der det lander.

Fellene

React 19 og web components

Har en web component en egenskap med samme navn som et attributt, setter React 19 egenskapen og ikke attributtet. Det gir tre feil, og de to første gir ingen feilmelding:

• Et boolsk attributt kan ikke sendes som tom streng. el.open = "" er usant, og setteren fjerner attributtet igjen. Send true.
• Et valg kan ikke låne navnet til en vanlig egenskap. autofocus="false" blir el.autofocus = "false", og en streng med innhold er sann. Legg valget i data-*, som React alltid sender som attributt.
• En getter må ha en setter. Uten den kaster React «Cannot set property», og attributtet kommer aldri fram.

Stavemåten er også ulik. React vil ha className, htmlFor og tabIndex, og tabIndex som tall. En byggefunksjon som returnerer HTML-navn, trenger derfor en egen utgave for React.

Fellene

Serveren og hydreringen

Ingen nettlesertest fanger den siste, for der finnes HTMLElement. Den må testes i et miljø uten DOM.

En sjekk som må slutte fra miljøet til hva utvikleren mente, gjetter feil i minst ett miljø. Lukk fella i typen framfor å gjette.

Fellene

Før komponenten er registrert

Fram til komponenten er registrert, er hver web component et vanlig HTMLElement, uten metoder og uten oppførsel.

• Registrer ved import, aldri i en effekt. En useEffect kjører etter første tegning. Kaller appen en metode på elementet før det, får den «reportSuccess is not a function».
• Et imperativt kall må vente på registreringen. En hjelpefunksjon som venter på customElements.whenDefined() for elementets eget tagnavn, gjør rekkefølgen likegyldig. Den sier fra i konsollen hvis det tar for lang tid.
• Flimmeret før registreringen løses i CSS. :not(:defined) gjelder til komponenten er registrert. Med den kan stilarket vise bare det første panelet, så den som rendrer, slipper å skrive hidden på resten.

Et skjemafelt, med og uten JavaScript

Slik ser det ut for den som bruker et designsystem bygget etter de syv kravene. Eksempelet er Fristil. Du installerer én pakke, importerer stilarket for det du trenger og skriver vanlig HTML.

import "@fristil/designsystem/tokens.css"
import "@fristil/designsystem/field.css"

<label class="fs-label">E-post</label>
<input class="fs-input" type="email">
<p class="fs-error-text">Skriv en gyldig adresse</p>

import { defineFsField } from "@fristil/designsystem/field"
defineFsField()

<fs-field invalid>
  <label class="fs-label">E-post</label>
  <input class="fs-input" type="email">
  <p class="fs-error-text">Skriv en gyldig adresse</p>
</fs-field>

Til venstre kjører det ingen kode. Ledeteksten, feltet og feilmeldingen er vanlige HTML-elementer med klasser fra systemet, og de ser riktige ut med én gang. Til høyre står nøyaktig de samme elementene, med ett element rundt. Det er <fs-field> som setter id, for og aria-describedby, slik at en skjermleser leser opp både ledeteksten og feilmeldingen.

Demoen som viser at det virker

Førstelinja er et spill bygget med Fristil, i tre utgaver: Kotlin med Datastar, React med TanStack Start og Astro med hele sider fra serveren. Samme spilltjener, samme skjerm, samme komponenter, og du kan spille mot noen som spiller i en annen utgave.

Den er også en stresstest. En komponent kan se riktig ut i en enhetstest og likevel ryke i det en ekte server eller React rendrer siden på nytt. TanStack Start-utgaven rendrer i nettleseren fra JSON, slik en vanlig CSR-app gjør, og de to andre rendrer på serveren.

Panelet i spillet: hva som faktisk gikk over nettverket, lest ut av trafikken

Tre helt ulike veier, og brukeren ser ingen forskjell. Spill den selv: forstelinja-react.up.railway.app, og trykk «Hva skjedde?» nede til høyre for å se trafikken mens du spiller.

Sjekkliste for ditt eget designsystem

Ett spørsmål per krav, og ett per felle. Kan du svare ja på alle, har systemet det som skal til.

Fristil: fristil.sobernetics.no · Pakke: @fristil/designsystem · Spillet: forstelinja-react.up.railway.app