Migrering

V2: Tokens oppdatering og Font-lasting

I versjon 2.0.0 har vi hatt fokus på tokens, semantiske farger og optimalisering av font-lasting.

Tokens

Målet for token-oppdateringen er å legge til rette for mer fart og flyt både i design og utviklingsfasen av løsninger. Vi har gjort en revisjon av semantikk og navngiving for tokens som vi håper vil gjøre det lettere å bruke dem aktivt i løsningene.

Codemod

Det er laget codemods for alle token-endringer i CSS, sass, less og js-format. Finner mer informasjon om disse i codemod-readme. For de fleste vil migreringen til nye tokens kunne gjøres på noen minutter.

For brukere av tailwind-pakken vår blir dette dessverre en litt mer manuell prosess. Ved migrering av tailwind-tokens brukt på aksel.nav.no tok denne prosessen ~15 minutter.

Prefiks

Vi har valgt å gå bort fra --navds, --navds-global-color og --navds-semantic-color prefiksene. Alle tokens har nå prefiks --a.

Endringer

Utenom endring i prefikser, er det bare semantiske farger som er påvirket av endringer i navn. Vi anbefaler å ta i bruk codemod-løsningen for oppdateringen, men tailwind-brukere kan bruke oversikten under.

Obs!! border-divider har nå alpha-verdi! Kan derfor være lurt å dobbelsjekke at dette fortsatt ser riktig ut i din løsning hvis du tidligere brukte divider.

Komponent-tokens og overskriving av tokens

Vi har oppdatert hvordan vi håndterer komponent-spesifikke tokens. Du vil ikke lengre kunne bruke eks --navds-button-color-primary-text til å style din egen kode eller gjøre overskrivinger. Du kan lese mer om den nye løsningen i "Tokens i kode".

Instansene der du har brukt komponent-tokens for å style din egen kode, vil automatisk bli oppdatert til ny semantisk verdi med codemod.

For de som har overskrevet tokens vil dette ikke lengre fungere som før og vi ønsker at alle tar egne valg for hvordan de håndterer dette. Ved kjøring av codemod vil derfor alle instansene med overskrevet designsystem-token bli prefikset med --v2-migration slik at du selv kan gjøre en CTRL + F og oppdatere dem.

Fonter

NAV har endelig en egen CDN løsning! Etter et supert initiativ fra frontend-platform har vi nå kunnet hoste våre egne font-filer. Ved oppdatering til v2 vil styling levert gjennom @navikt/ds-css gå fra 196kB til 96kB (uten gzip). I praktisk test med nextjs build ble css-bundle 78kB mindre!

For mange vil dette bare "funke", men er noen grep som må gjøres for å sikre at dette fungerer som ønsket for alle.

Oppdatere CSP (content security policy)

Hvis du har satt opp en CSP i løsningen din, kan det hende du må oppdatere den for å tillate lasting fra cdn.nav.no. Kan lese mer om font-src på mdn.

Preload

Vi setter font-display: swap, som tilsier at en fallback-font vil bli lastet når man ikke får tak i ønsket font raskt nok. For å unngå FOUT anbefaler vi at man legger til en link-tag med preload i document-head. Kan lese mer om dette i denne web-dev demoen.

Vi har også valgt å bruke den oppdaterte versjonen av Source Sans Pro, som nå heter Source Sans 3. I kode importeres den fortsatt som font-family:"Source Sans Pro" slik at den fortsatt er bakoverkompatibel, og ikke vil være noe man trenger å oppdatere selv.

Beta til V1

Designsystemet er endelig ute av Beta! Og med det kommer det noen breaking changes som vi forklarer litt her.

Samversjonering

Med v1-release er alle pakkene samversjonerte. Dette vil si alle pakker har samme versjon, uansett om siste release kun endret på én av pakkene. Bruker du ds-css v1.1.0, bør du også bruke ds-react v1.1.0.

Codemod

Breaking changes er kjedelige, noe vi er veldig klare over. Vi har derfor prøvd oss på en codemod-pakke (@navikt/ds-codemod) som kan gjøre migrering til nyere versjoner litt lettere. Noen breaking changes i komponenter vil du kunne fikse via @navikt/ds-codemod, andre må gjøres selv. Vi anbefaler å sjekke alle komponenter som berører deg fra listen under. Du finner en codemod README på Github, i Designsystemet-repoet.

Breaking changes

Accordion og ReadMore (❌ ikke codemod)

renderContentWhenClosed-prop er fjernet fra begge komponentene. Normal oppførsel er nå alltid å ha innholdet i dom-en. Dette vil la f.eks. Google indeksere innholdet bedre, og det er en bedre uu-praksis fordi react-collapse hadde noen uu-bugs. Vi har ikke laget noen codemods for dette og anbefaler alle å dobbelsjekke at alt funker som forventet når du gjør denne endringen.

Komponentene bruker heller ikke pakken "react-collapse" lengre. Dette vil bare påvirke deg om du manuelt overskriver styling på klassene ReactCollapse--collapse og ReactCollapse--content.

Button (❌ ikke codemod)

Nye props

• icon: Ikon som rendres i knapp
• iconPosition: Om ikonet skal være venstre/høyrestilt

Bruk av ikoner i knapp er nå endret, så alle som i dag bruker ikoner i <Button /> må oppdatere koden sin. Endingen er gjort for å ha mer kontroll på rendring av ikon og plasseringen i selve knappen.

Tabs (✅ codemod)

• loop er flyttet fra Tabs.Tablist til Tabs (codemod fikser)
• iconPosition er flyttet fra Tabs.Tab til Tabs (codemod fikser)

SpeechBubble heter nå Chat (🟡 delvis codemod, se under)

SpeechBubble og SpeechBubble.Bubble endrer navn til Chat og Chat.Bubble. Codemod tar seg av renamingen.

• topTextprop er nå delt opp i name og timestamp. Codemod vil legge topText inn i name, men man må selv manuelt justere teksten hvis man har tatt i bruk en timestamp i topText.
• illustration prop heter nå avatar (codemod fikser)
• illustrationBgColor prop heter nå avatarBgColor (codemod fikser)

Pagination (✅ codemod)

Komponenten var tidligere bare tilpasset interne-flater og brøt vår egen konvensjon på sizing da medium bare var 32x32px. Vi har derfor forslkjøvet sizing-skalaen og lagt til en versjon tilpasset eksterne flater.

• size="medium" er nå size="small" (codemod fikser)
• size="small" er nå size="xsmall" (codemod fikser)
• Bruk uten size-prop blir satt til size="medium" av codemod

På grunn av hvordan flyttingen av sizing-skalaen fungerer er det ikke mulig å kjøre codemod flere ganger uten at størrelsen blir nedjustert hver gang. Derfor blir det automatisk satt en prop data-version="v1" som codemoden bruker som filter. Denne kan beholdes eller fjernes etter migrering ettersom hva man ønsker.

Popover/Helptext (❌ ikke codemod)

Vi har migrert til et nytt "floating"-api og bruker ikke "react-popper" eller "popperjs" lenger. For deg som bruker vil dette forhåpentligvis ikke ha noen uventede effekter, men placement auto, auto-start og auto-end er ikke lengre tilgjengelig. Vi fant ingen som eksplisitt hadde satt dette, så vi laget ikke en codemod for dette.

CopyToClipboard (❌ ikke codemod)

iconPlacement-prop er renamet til iconPosition. Har nå samme navn som eks Button og Tabs.Tab. Vi har fokusert på codemods til core-pakken og har ikke laget en codemod til denne

ConfirmationPanel (❌ ikke codemod)

Ref er flyttet fra wrapper (div) til checkbox (input). Vil bare påvirke brukere av ref-prop

StepIndicator blir Stepper (❌ ikke codemod)

Se mer info under Deprecation

Deprecation

I systemet vårt har vi nå flere komponenter som ble laget og lagt til i designsystemet med fokus på hurtighet heller enn langsiktighet. Fordi vi setter et større fokus på stabilitet ønsker vi samtidig å avvikle forvalting av noen komponenter.

Vi kan f.eks. velge å avvikle forvaltning av komponenten når vi erstatter en komponent med en annen, når en komponent ikke har blitt oppdatert på lenge eller når komponenten fremdeles er i beta/er ustabil. Vi håper å gjøre migreringen lettest mulig.

MicroCard

Denne komponenten blir i dag brukt på nav.no sine sidemaler, men med et nyere og mer oppdatert design. Etterhvert håper vi at vi kan gjøre det lettere å ta i bruk kompoentene brukt på sidemalene, men for nå ønsker vi ikke å forvalte utdaterte komponenter som dette i koden vår.

Legger ved lenke til koden hvis man vil kopiere den inn i lokalt prosjekt: Css og React (overridablecomponent kan her erstattes med en <a>-tag eller tilsvarende)

PageHeader

Avvikles av samme grunn som MicroCard

Lenke til koden her: Css og React .

Menu

Avvikles av samme grunn som MicroCard

Lenke til koden her: Css og React .

StepIndicator

Komponenten erstattes med Stepper som finnes i både horisontal og vertikal versjon. På grunn av API-endring i hva activeElement er, har vi valgt å ikke lage en codemod for denne. Endringene du som utvikler og bruker av kompontenten må gjøre er:

• Importere Stepper fra "ds-react"
• Rename StepIndicator og StepIndicator.Step til Stepper og Stepper.Step
• Sette orientation="horizontal"(default er vertikal nå)
• Sjekke at activeElement og onStepChange-indekseringen stemmer (step 1 returnerer nå 1 og ikke 0, som matcher den visuelle indekseringen)

Divider

@navikt/ds-react-internal sin <Divider /> komponent heter nå <Dropdown.Menu.Divider />.

Misc

For å forminske "bloating" har vi kvittet oss med flere unødvendige dependencies. Vi håper det vil bli lettere å ta i bruk Designsystemet for de som f.eks bruker skypack eller lignende verktøy. Vi har en del å gå på for å optimalisere pakkene, men er et steg i riktig retning.

Noen av endringene kan påvirke løsningen deres hvis dere ikke selv har lagt til imports, men bruker dem via ds-react pakken. Dette anbefaler vi ikke, men antar yarn/npm eller build-step sier ifra hvis dette er tilfellet.

Endringer i dependencies:

• Depender ikke lengre på @material/ui.
• Depender ikke lengre på react-popper og @popperjs/core
• Byttet ut classnames med clsx
• Bruker nå @floating-ui/react-dom-interactive for popover/tooltip handling
• Depender ikke lengre på react-collapse. Bruker egen animasjon for Accordion, ReadMore og ExpandableRow (Table).
• ErrorMessage er nå <p>, var tidligere <div>.
• Label er nå <label>, var tidligere <p>.
• Checkbox og Radio sin <label> bruker nå <span> instedenfor <div>. Kan ende opp med valideringsfeil i dom hvis du rendrer noe annet enn tekst i label, så greit med en dobbelsjekk der.
• Vi har også flyttet id-håndteringen til en lokal løsning i stedet for npm-pakken uuid. Komponenter i React 17 bruker nå en indeksert id, men React sin useId-hook for React 18 brukere.

nav-frontend pakker

Vi har valgt å ikke støtte nav-frontend pakkene fremover og håper de fleste vil velge å bruke de nye løsningene våre for fremtidige prosjekt eller refaktoreringer.

For deg som vil oppdatere prosjektet ditt til det nye designsystemet vil det dessverre kunne bli en del arbeid basert på hvor mye av det gamle du har brukt. En god start er å ta en titt på "kom i gang som utvikler"-artikkelen som forklarer hvordan de nye løsningene tas i bruk.

Noen tekniske fordeler med bruk av de nye løsningene for deg som utvikler er

• Mindre npm-pakker og versjoner: Prosjektet ditt vil gå fra ofte 20+ npm-pakker for nav-frontend til 2-5 nå. Alle de nye pakkene har også samme versjon, slik at du lettere kan holde alt oppdatert.
• Trenger ikke lengre Less-støtte: All ny styling er ren CSS og du kan skrive deg bort fra eks craco eller andre gamle less-plugins som ofte ikke lengre er aktivt støttet.
• Fremtidig støtte og nye oppdaterte komponenter.
• forwardRef: Alle komponenter bruker nå forwardRef, som gir deg mer kontroll om ønsket.
• Plug and play: Funker rett ut av boksen for de fleste rammeverk. Vite, Next, Gatsby, CRA, Parcel etc.

Generelle API-endringer

De fleste komponentene har fått oppdatert API-et sitt. Ved oppdaterting fra gammel til ny komponent kan det være lurt å ta en titt på props-seksjonene da eksemplene under ikke vil dekke alle endringene.

Størrelser

I nav-frontend brukte flere komponenter propnavnene type, kompakt og mini for diverse padding/margin/typo endringer. I de nye pakkene vil størrelser settes konsekvent med size. size="small" er ofte ment for interne flater og vi spesielt for interaktive komponenter anbefaler vi å bruke size="medium".

Varianter

For komponenter med visuelle varianter ble type ofte brukt. Nå vil vi prøve å konsekvent bruke variant for disse tilfellene.

Skjemaelementer

RadioGroup og CheckboxGroup kan nå selv styre checked-state for input-elementene med value og tilhørende onChange-prop. Du trenger da ikke lengre å sette checked true/false på hvert av Checkbox/Radio-elementene med tilhørende logikk.

feil + feilId er endret til error + errorId for alle skjemaelementer. Error id settes også nå på aria-describedby ovenfor aria-errormessage, da sistnevnte ikke har så god skjermleserstøtte.

Alertstripe (✅ Alert)

Bekreftcheckbokspanel (✅ ConfirmationPanel)

inputProps er fjernet, "rest"-props blir nå satt direkte på input-elementet i ConfirmationPanel

Checkbokspanelgruppe ❌

Vi har valgt å ikke ta med CheckboksPanel og CheckboksPanelGruppe inn i nye løsninger.

Checkboks (✅ Checkbox)

State kan lettere håndteres med hjelp av onChange og value i CheckboxGroup nå.

Chevron ❌

Chevron er nå et ikon i @navikt/ds-icons-pakken. Finner variantene i ikonsøket vårt under "chevron".

Ekspanderbartpanel (🟡 Accordion)

Accordion er ment som erstattning for Ekspanderbartpanel. Bruk og funksjonalitet er litt endret på, så anbefaler å referer til dokumentasjonen når du migrerer.

Vi er klar over at Accordion ikke dekker helt den samme bruken som Ekspanderbartpanel og har det på todo-lista å få sett på det.

Etikett (✅ Tag)

Feiloppsummering (✅ ErrorSummary)

FnrInput ❌

Vi har ikke tatt denne med videre i pakkene våre. Kan bruk vår TextField-komponent og NAVs fnr-valideringspakke (github.com/navikt/fnrvalidator)

Hjelpetekst (✅ HelpText)

Ikonknapper ❌

Vi har ikke lengre noen knapper med ikon-preset. Kan replikeres med hjelp av ikonpakken vår @navikt/ds-icons.

Input (✅ TextField)

Vi har ikke lengre en egen bredde-prop. Bruke heller native input-prop size eller styling.

Knapp (✅ Button)

Lenke (✅ Link)

Lenkepanel (✅ LinkPanel)

Lesmerpanel ❌

Vi har ikke tatt med denne komponenten inn i de nye pakkene, kan se om alternativene under fungerer som erstatning.

Lukknapp ❌

Se over på "Knapp".

Modal (✅ Modal)

Har nå en egen komponent Modal.Content som legger på en default-padding.

Panel (✅ Panel)

Popover (✅ Popover)

Har nå en egen komponent Popover.Content som legger på en default-padding.

Radio (✅ Radio)

RadioPanelGruppe ❌

Vi har valgt å ikke ta med RadioPanelGruppe inn i nye løsninger.

Select (✅ Select)

Se dokumentasjon for API-endringer.

Skjemagruppe (🟡 Fieldset)

Vi har en egen generell Fieldset-komponent i systemet, men har valgt å ikke dokumentere denne da den er mest ment for internt bruk.

Snakkeboble (✅ Chat)

Spinner (✅ Loader)

Stegindikator (✅ Stepper)

Tabell (✅ Table)

Table er nå en egen react-komponent. Sjekk ut dokumentasjonen for å se hvordan du kan erstatte din tabell med en komponenten.

Tabs (✅ Tabs)

Tabs har nå fått tabpanel integrert i komponenten.

Tekstomrade ❌

Vi har ikke denne komponenten med inn i de nye pakkene. Du kan finne parser-pakken ble brukt for denne løsningen på github.

Textarea (✅ Textarea)

ToggleGruppe/ToggleKnapp (🟡 ToggleGroup)

Veileder ❌

Vi har ikke denne komponenten med i de ny pakkene. Som erstatter tenker vi GuidePanel nevnt under.

Veilederpanel (✅ GuidePanel)

nav-frontend-typografi til V1

Ikke alle typografikomponentene i @navikt/ds-react er én-til-én med de i nav-frontend-typografi, så så vi foreslår at du spør en designer om du er usikker på hvilken komponent du skal velge. Du kan også spørre en av oss i Designsystemet (#designsystemet i Slack).

Tekststørrelse og heading-nivå

Overskrifters tekststørrelse er nå uavhengig av heading-nivået. Det betyr at du står fritt til å sørge for at overskrift-hierarkiet stemmer for din nettside, uavhengig av visuelt hierarki. Før kunne det være trøblete om men f.eks. ønsket seg en h1, men <Sidetittel> opplevdes som for stor.

En direkte oversettelse fra gamle til nye komponenter, hvor man bevarer størrelsene, ser sånn ut:

Brødtekst

De nye komponentene for brødtekst heter <BodyLong> og <BodyShort>. Altså blir <Normaltekst> i stedet til <BodyLong>/<BodyShort>.

<BodyLong> er ment å brukes der det er snakk om løpende tekst, f.eks. i en artikkel. I situasjoner der teksten med fordel kan være mer kompakt skal <BodyShort> brukes, for den har en lavere linjehøyde.

Ny brødtekst-størrelse er 18px. Om du bygger/vedlikeholder grensesnitt med kompakt design (les; interne flater) og ønsker å fortsette å bruke 16px brødtekst, så kan du bruke <BodyLong size="small"> og <BodyShort size="small">.

Andre typografikomponenter