Migrering til Punkt 19

Kort oppsummert

De fleste prosjekter trenger ingen eller svært få endringer. Vi har kjørt verktøyet mot flere reelle kodebaser i Oslo kommune, og de fleste kom tilbake uten et eneste treff. De responsive hjelpeklassene er rett og slett lite brukt. Det er også hele grunnen til at vi kutter dem.

Kjør verktøyet

Verktøyet tar én sti: mappa koden din ligger i. Det går gjennom alt under den, så det enkleste er å peke på rota av prosjektet. node_modules, dist, build og andre byggemapper hoppes over automatisk.

npx @oslokommune/punkt-migrate@19 . --dry-run

Vil du avgrense til en del av prosjektet, bytt ut . med den mappa. Den heter ./src i mange prosjekter, men kan like gjerne hete ./app, ./components eller ./resources/views. Ligger koden i flere mapper, er det enklere å kjøre på rota enn å kjøre én gang per mappe.

--dry-run skriver ingenting. Du får en rapport med fire kategorier:

Kategori	Betyr
Endret	Trygt skrevet om. Ingen oppfølging.
Fjernet	Klassen finnes ikke lenger. Stilen forsvinner, så se over.
Droppet	Overflødig etter omskrivingen. Ingen oppfølging.
Flagget	Krever at du vurderer det selv.

Er rapporten grei, kjør uten --dry-run. Verktøyet nekter å skrive hvis du har endringer som ikke er sjekket inn, så du alltid kan se hva det gjorde med git diff.

npx @oslokommune/punkt-migrate@19 .

Verktøyet avslutter med kode 1 hvis noe havnet i Flagget, så du kan kjøre det i CI.

Breakpoints: 6 → 4

phablet (576px) og desktop (1600px) fjernes. De fire som blir, beholder verdiene sine.

Breakpoint	Verdi	Status
mobile	0	Uendret
phablet	36rem (~576px)	Fjernes
tablet	48rem (~768px)	Uendret
tablet-big	64rem (~1024px)	Uendret
laptop	80rem (~1280px)	Uendret
desktop	100rem (~1600px)	Fjernes

Hjelpeklasser med -phablet-up rundes opp til -tablet-up. Stilen slår altså inn på en bredere skjerm enn før. Mobilvisningen er aldri berørt.

<!-- før -->
<h1 class="pkt-txt-28 pkt-txt-54--phablet-up">Overskrift</h1>

<!-- etter -->
<h1 class="pkt-txt-28 pkt-txt-54--tablet-up">Overskrift</h1>

Klasser med -desktop-up fjernes uten erstatning, fordi det ikke finnes noe breakpoint over. Over 1600px arver elementet det laptop-up eller lavere setter. Verktøyet rapporterer hver eneste fjerning med fil og linjenummer.

Klasser med --mobile-up mister suffikset, fordi de alltid var identiske med basisklassen.

tablet-big og laptop trenger ingen migrering.

Bredder på container og grid

.pkt-container--phablet og .pkt-grid--desktop og de andre breddemodifikatorene beholdes alle sammen. De er max-width-verdier, ikke breakpoints. Navnet er den eneste koblingen. Du trenger ikke gjøre noe med dem.

I SCSS

bp('phablet-up') og bp('desktop-up') byttes til bp-up() med verdien, så terskelen står der den står:

// før
@include bp('phablet-up') { ... }

// etter
@include bp-up(36rem) { ... }

Intervallnavnene bp('mobile'), bp('phablet'), bp('laptop') og alle *-to-*-navnene byttes til media queryen de tilsvarer.

Henter du verdier rett ut av kartene, blir map.get($spacing, 'size-52') skrevet om til 'size-56'. map.get($breakpoints, 'phablet') blir flagget, siden den ikke har noen erstatning du kan slå opp: bruk 36rem direkte. Dette er verdt å få med seg, for en fjernet nøkkel gir null, og da forsvinner hele deklarasjonen uten at Sass sier fra.

Dette gjelder også <style lang="scss">-blokker i .vue, .astro og .svelte, ikke bare frittstående .scss-filer.

Punkt 18.9 advarte med @warn når du brukte et navn som skulle forsvinne. I 19 stopper bp('phablet'), bp('phablet-up') og bp('desktop-up') bygget med en @error som sier hva du skal bruke i stedet. Det er med vilje: uten den ville navnet blitt sendt rett inn i media queryen, og nettleseren ville droppet regelen uten å si fra.

Spacing

Åtte verdier som aldri har vært i Figma fjernes, og snappes til nærmeste godkjente verdi. Halvtrinn rundes opp.

Fjernes	Blir
size-5	size-6
size-15	size-16
size-30	size-32
size-50	size-48
size-52	size-56
size-60	size-64
size-75	size-72
size-100	size-104

size-10 og size-20 blir stående selv om de heller ikke er i Figma. De er for mye i bruk.

Dette endrer piksler. Verktøyet gjør omskrivingen, men resultatet bør ses over visuelt.

gap-size-* fjernes

Hjelpeklassene gap-size-0 til gap-size-128 forsvinner. De har aldri vært dokumentert, og gap virker uansett bare på flex- og grid-beholdere, i motsetning til margin og padding, som virker overalt.

Det finnes ingen erstatning. Verktøyet rapporterer hver forekomst med verdien du skal sette:

Fjernet  gap-size-24 (sett gap: 1.5rem selv)

Responsiv spacing flyttes ut av base

pkt-base.css inneholder i dag 2 610 responsive spacing-klasser, over halvparten av alle reglene i fila, og nesten ingen bruker dem. I Punkt 19 ligger de i en egen fil du henter inn selv.

Dette gjelder uansett hvordan du henter Punkt. Klassene forsvinner også fra pkt, altså fra hele bundlen, ikke bare fra pkt-base.

Med SCSS:

@use '@oslokommune/punkt-css/dist/scss/pkt';
@use '@oslokommune/punkt-css/dist/scss/pkt-spacing-responsive'; // bare hvis du trenger den

Fra CDN:

<link href="https://punkt-cdn.oslo.kommune.no/19/css/pkt.min.css" rel="stylesheet" />
<link
  href="https://punkt-cdn.oslo.kommune.no/19/css/pkt-spacing-responsive.min.css"
  rel="stylesheet"
/>

Bruker du @layer? Da finnes pkt-spacing-responsive.layer ved siden av pkt.layer, på samme måte som for resten av Punkt:

@use '@oslokommune/punkt-css/dist/scss/pkt.layer';
@use '@oslokommune/punkt-css/dist/scss/pkt-spacing-responsive.layer';

Det er viktig at den havner i samme layer som resten av Punkt. Ligger den utenfor, vinner den over alt annet, også over dine egne overstyringer. Se oppsettet med @layer.

Målt mot 18.9: pkt-base.min.css faller fra 31 til 13 kB gzipet, og pkt.min.css fra 60 til 42 kB. Responsiv spacing er den største enkeltposten i det, men de fjernede verdiene, gap-size-* og --mobile-up-klassene teller også med. Trenger du den responsive spacingen, koster den 4 kB gzipet som egen fil.

Har du spesielle behov? Utvid listene

Bruker du SCSS, bestemmer du selv hva som ligger i $spacing og $breakpoints. Punkt genererer hjelpeklassene ut fra listene, så du kan beholde en verdi vi fjerner, eller legge til en terskel vi aldri har hatt, uten å vente på oss.

Legg oppsettet i en egen fil, og hent den inn før Punkt:

// punkt-config.scss
@use 'sass:map';
@use '@oslokommune/punkt-css/dist/scss/abstracts/variables' as v;

// Ta tilbake phablet
v.$breakpoints: map.merge(
  v.$breakpoints,
  (
    'phablet': 36rem,
  )
);

// Behold size-52, og legg til en egen verdi
v.$spacing: map.merge(
  v.$spacing,
  (
    'size-52': 3.25rem,
    'size-200': 12.5rem,
  )
);

// main.scss
@use 'punkt-config';
@use '@oslokommune/punkt-css/dist/scss/pkt';

Med map.merge beholder du hele lista vår og legger bare til dine egne verdier. Du slipper å kopiere den, og du kan ikke komme i skade for å fjerne en verdi komponentene våre trenger.

Responsiv spacing følger ikke med automatisk. Legger du til et breakpoint, får du responsive klasser for typografi, grid og synlighet med det samme, men spacing bare hvis du også henter inn pkt-spacing-responsive.

Rekkefølgen i $spacing bestemmer hvilken klasse som vinner når to av samme type står på samme element, så behold rekkefølgen fra vår liste hvis du er i tvil.

Hva verktøyet ikke kan gjøre

Verktøyet skriver aldri om noe det ikke er sikkert på. Det flagger i stedet, med fil og linjenummer:

• Klassenavn som settes sammen i kode, som `pkt-cell--span${n}-phablet-up`. Her vet ikke verktøyet hva navnet blir.
• Kollisjoner det ikke kan løse, for eksempel når en phablet-klasse og en tablet-klasse ligger i hver sin gren av et classNames()-kall.
• Fjerninger som krever en strukturell endring, som å slette et helt argument eller en objektnøkkel.
• Bygget CSS lagt inn i repoet. Har du en kopi av Punkt sin CSS liggende, hopper verktøyet over den og sier fra. Den erstatter du ved å oppgradere pakka.

Henter du Punkt fra CDN?

Verktøyet migrerer koden din, ikke CDN-lenkene. Peker du på en versjonert sti, som /18/css/pkt.min.css, får du Punkt 19 først når du selv bytter til /19/. Da bør du kjøre verktøyet i samme slengen.