Tilpasning

Du tilpasser Fristil ved å sette CSS-variabler i din egen CSS. Verdiene som følger med pakken er standardverdier, og dine egne vinner over dem.

Tre veier, i den rekkefølgen du bør prøve dem:

Vei	Til hva
Tokens	Farger, på tvers av hele systemet
Komponentvariabler	Form og størrelse på én komponent
Vanlige regler	Alt annet

Egne farger

Det er én vei inn: din egen CSS, lastet etter tokens.css. Alt Fristil sender ut ligger i et cascade layer (@layer fristil), og CSS uten layer vinner alltid over CSS i et layer, uansett spesifisitet. Du trenger verken !important eller lange selektorer.

Standarden er å la være: Fristils egne farger er kontrollert mot WCAG AA i begge temaer, og du trenger ikke skrive noe. Skal du endre dem, velger du hvor grovt du tar i.

Du vil	Skriv
Endre én farge	Cella, --fs-color-accent-fill
Endre en hel familie	De ni rollene, --fs-color-accent-surface til --fs-color-accent-content
Gi hele systemet organisasjonens farger	Ingenting. Lag et tema, så skrives fila for deg

Generatoren er ikke en egen mekanisme. Den setter de samme variablene, for begge temaer. Fila den skriver legger seg i sitt eget lag, fristil-tema, slik at din egen CSS fortsatt vinner over temaet.

Skriver du celler selv, er kontrastløftene dine å holde. fristil sjekk-tema tema.css sier hvilken celle som ryker og hvorfor.

Variablene

:root {
  --fs-color-accent-fill: #7c3aed;
  --fs-color-accent-content: #ffffff;
}

Overstyrer du, eier du kontrasten

Fargene i Fristil er kontrollert mot WCAG AA, i begge temaer. Bytter du en av dem, gjelder ikke den garantien lenger, og paret fargen inngår i må kontrolleres på nytt. --fs-color-accent-fill er for eksempel både knappebakgrunn under --fs-color-accent-content og rammefarge på en avkryssingsboks som er huket av.

Lyst og mørkt

Uten at du gjør noe, følger fargene maskinens innstilling. En side som vil bestemme selv setter data-theme på <html>:

<html data-theme="light">

Attributtet er en temagrense

data-theme virker på et hvilket som helst element, ikke bare på roten. Elementet og alt under det får temaet, og resten av siden står urørt:

<div data-theme="dark">
  <button class="fs-button">Denne er mørk</button>
</div>

Et tema kan ligge inne i et annet, begge veier. En lys boks i en mørk seksjon er like gyldig som det motsatte.

En innebygd komponent låser sitt eget tema

Legger du Fristil inn i en side du ikke eier, er dette måten å gjøre det på. Sett attributtet på komponentens eget rotelement, så er den lys uansett hva maskinen står på, og verten røres ikke:

<div data-theme="light">
  <table class="fs-table">
    <caption class="fs-sr-only">Fakturaer</caption>
  </table>
</div>

Du skal ikke sette data-theme på vertens <html>. Det er et globalt attributt som tilhører siden, ikke deg.

Brukeren kan få velge

fs-theme-control på en radioknapp gjør value til et temavalg, i ren CSS:

<label class="fs-toggle-group__option">
  <input class="fs-theme-control" type="radio" name="tema"
         value="dark" /> Mørkt
</label>

Tre verdier betyr noe: auto, light og dark. light og dark vinner over data-theme på <html>, så serveren kan sende det lagrede valget mens et klikk slår igjennom med én gang. auto har ingen temablokk, så der står serverens data-theme igjen. Kontrollen lagrer ingenting selv. Se La brukeren velge tema for hele mønsteret.

Fargeskjemaet er ditt å velge

color-scheme avgjør hvordan nettleseren tegner sine egne flater: rullefelt, nedtrekkslista til en <select> og kalenderpanelet i et datofelt. Fristil setter den der noen har valgt et tema: på [data-theme="light"], på [data-theme="dark"] og på de tre valgene til temavelgeren. Bar :root får den aldri.

Grunnen er at egenskapen arves nedover, så en verdi på roten gjelder hele dokumentet, også en vertsside som aldri ba om det. Et barn kan melde seg ut med color-scheme: normal, men det er en motregel verten ikke skal måtte skrive. Vil du at nettleserens flater skal følge systemet på hele siden, skriver du én linje selv:

:root {
  color-scheme: light dark;
}

Det er den samme avtalen som for lagrekkefølgen: én linje hver, og begge er dine.

Bruker du temavelgeren, skal du ikke skrive den linja. Hvert av de tre valgene setter color-scheme selv: light gir light, dark gir dark, og «Følg systemet» gir light dark, altså beskjeden om at siden fungerer i begge og at nettleseren kan velge etter systemet. Skriver du den likevel, utenfor et lag, slår regelen @layer fristil, og nettleserens flater blir låst til systemet mens brukeren har valgt noe annet. Å legge den i et lag foran fristil hjelper ikke: rekkefølgen er alt etablert av tokens.css, som lastes først, så en senere @layer-setning legger laget bak.

Per tema

Overstyringen under «Egne farger» gjelder begge temaer. Vil du ha ulike verdier, skriver du dine egne regler:

:root {
  --fs-color-accent-fill: #7c3aed;
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --fs-color-accent-fill: #c4b5fd;
  }
}

[data-theme="light"] {
  --fs-color-accent-fill: #7c3aed;
}

[data-theme="dark"] {
  --fs-color-accent-fill: #c4b5fd;
}

Bruker du temavelgeren, må de to siste blokkene ha dens selektor ved siden av, slik Fristils egne har:

[data-theme="light"],
:root:has(.fs-theme-control[value="light"]:checked) {
  --fs-color-accent-fill: #7c3aed;
}

[data-theme="dark"],
:root:has(.fs-theme-control[value="dark"]:checked) {
  --fs-color-accent-fill: #c4b5fd;
}

Velgeren setter ikke data-theme, for CSS kan ikke skrive et attributt. Uten selektoren traff ingen av blokkene dine når brukeren valgte et tema, og Fristils egen farge sto igjen.

Alle fire blokkene må være med. De to data-theme-blokkene deklarerer hver sin verdi rett på elementet som bærer attributtet, og en deklarasjon på elementet selv vinner over en verdi det arver, uansett hvilket lag arven kom fra. Utelater du [data-theme="light"], står Fristils egen farge inne i en lys temagrense mens din gjelder ellers på siden.

Form og størrelse

Farger er ikke det eneste du kan endre. Hver komponent har egne variabler for form og størrelse:

:root {
  --fs-button-radius: 9999px;
  --fs-input-radius: 0;
}

Hvor du setter den avgjør hvor langt den rekker

Variablene arves, som alle CSS-variabler. Stedet du skriver deklarasjonen er derfor det eneste som bestemmer rekkevidden, og du trenger ingen egen mekanisme for å begrense den.

På :root gjelder den hele appen, som i eksempelet over. Skriver du den på din egen klasse i stedet, gjelder den det elementet og alt som ligger inni:

Eksempel

Ren HTML

<div class="fs-card">
<h3 class="fs-heading" data-size="s">Standard</h3>
<p class="fs-paragraph">Verdiene som følger med pakken.</p>
<button class="fs-button">Åpne saken</button>
</div>

<div class="fs-card tett-panel">
<h3 class="fs-heading" data-size="s">Tett panel</h3>
<p class="fs-paragraph">Samme markup, én klasse mer.</p>
<button class="fs-button">Åpne saken</button>
</div>

.tett-panel {
--fs-card-padding: var(--fs-spacing-2);
--fs-card-radius: 0;
--fs-button-padding: var(--fs-spacing-1) var(--fs-spacing-3);
}

Markupen er den samme i begge. Den eneste forskjellen er klassen tett-panel, og den er din, ikke vår. Knappen inni blir smalere uten at du rører knappen: den arver variabelen fra kortet.

Det gir deg tre rekkevidder med den samme mekanismen:

Hvor du skriver den	Hvor langt den rekker
:root	Hele appen
Din egen klasse på en beholder	Alt inni den beholderen
Din egen klasse på komponenten	Bare den ene

Tabellen under er et oppslagsverk over hver variabel som finnes. Hva den enkelte gjør, og et eksempel som viser det, står på komponentens egen side.

Variabel	Standard
--fs-button-padding	var(--fs-spacing-2) var(--fs-spacing-4)
--fs-button-radius	var(--fs-spacing-1)
--fs-button-border-width	1px
--fs-button-font-weight	var(--font-weight-medium)
--fs-button-line-height	var(--fs-line-height-default)
--fs-heading-font-weight	var(--font-weight-bold)
--fs-heading-line-height	var(--fs-line-height-heading)
--fs-paragraph-line-height	var(--fs-line-height-article)
--fs-badge-padding	var(--fs-spacing-0-5) var(--fs-spacing-2)
--fs-badge-radius	var(--fs-spacing-4)
--fs-alert-padding	var(--fs-spacing-3) var(--fs-spacing-4)
--fs-alert-radius	var(--fs-spacing-1)
--fs-alert-accent	var(--fs-spacing-1)
--fs-card-padding	var(--fs-spacing-4)
--fs-card-radius	var(--fs-spacing-2)
--fs-divider-space	var(--fs-spacing-4)
--fs-spinner-size	var(--fs-spacing-6)
--fs-spinner-thickness	2px
--fs-table-cell-padding	var(--fs-spacing-2) var(--fs-spacing-3)
--fs-list-gap	var(--fs-spacing-1), men var(--fs-spacing-2) i divided
--fs-tag-padding	var(--fs-spacing-0-5) var(--fs-spacing-2)
--fs-tag-radius	var(--fs-spacing-1)
--fs-avatar-size	var(--fs-spacing-10)
--fs-avatar-radius	var(--fs-spacing-1)
--fs-skeleton-height	var(--fs-spacing-4), men var(--fs-spacing-10) i circle
--fs-skeleton-radius	var(--fs-spacing-1)
--fs-breadcrumbs-gap	var(--fs-spacing-2)
--fs-pagination-gap	var(--fs-spacing-1)
--fs-pagination-size	var(--fs-spacing-10)
--fs-pagination-radius	var(--fs-spacing-1)
--fs-progress-fill	var(--fs-color-accent-fill), og data-color endrer den
--fs-progress-track	var(--fs-color-neutral-surface)
--fs-progress-height	var(--fs-spacing-2)
--fs-progress-radius	var(--fs-spacing-1)
--fs-skip-link-padding	var(--fs-spacing-2) var(--fs-spacing-4)
--fs-skip-link-radius	var(--fs-spacing-1)
--fs-accordion-radius	var(--fs-spacing-1)
--fs-accordion-padding	var(--fs-spacing-3) var(--fs-spacing-4)
--fs-dialog-width	min(32rem, 100%, calc(100vw - var(--fs-spacing-8)))
--fs-dialog-padding	var(--fs-spacing-5)
--fs-dialog-layer	40
--fs-dialog-radius	var(--fs-spacing-2)
--fs-tooltip-width	16rem
--fs-tooltip-padding	var(--fs-spacing-1) var(--fs-spacing-2)
--fs-tooltip-radius	var(--fs-spacing-1)
--fs-paragraph-width	70ch
--fs-paragraph-gap	var(--fs-spacing-3)
--fs-tabs-gap	var(--fs-spacing-1)
--fs-tabs-padding	var(--fs-spacing-2) var(--fs-spacing-4)
--fs-tabs-panel-space	var(--fs-spacing-4)
--fs-error-summary-padding	var(--fs-spacing-4)
--fs-error-summary-radius	var(--fs-spacing-1)
--fs-file-upload-padding	var(--fs-spacing-2)
--fs-file-upload-radius	var(--fs-spacing-1)
--fs-avatar-stack-overlap	calc(var(--fs-spacing-2) * -1)
--fs-popover-width	min(20rem, calc(100vw - var(--fs-spacing-8)))
--fs-popover-padding	var(--fs-spacing-3)
--fs-popover-radius	var(--fs-spacing-1)
--fs-popover-top	settes av komponenten
--fs-popover-left	settes av komponenten
--fs-toast-space	var(--fs-spacing-4)
--fs-toast-width	min(24rem, calc(100vw - var(--fs-spacing-8)))
--fs-toast-padding	var(--fs-spacing-3) var(--fs-spacing-4)
--fs-toast-radius	var(--fs-spacing-1)
--fs-toast-layer	60
--fs-suggestion-max-height	calc(var(--fs-spacing-10) * 4)
--fs-suggestion-radius	var(--fs-spacing-1)
--fs-suggestion-layer	30
--fs-suggestion-option-padding	var(--fs-spacing-2) var(--fs-spacing-3)
--fs-input-padding	var(--fs-spacing-2) var(--fs-spacing-3)
--fs-input-radius	var(--fs-spacing-1)
--fs-textarea-min-height	calc(var(--fs-spacing-4) * 5)
--fs-textarea-padding	var(--fs-spacing-2) var(--fs-spacing-3)
--fs-textarea-radius	var(--fs-spacing-1)
--fs-select-radius	var(--fs-spacing-1)
--fs-select-option-padding	var(--fs-spacing-2) var(--fs-spacing-3)
--fs-select-viewport-margin	var(--fs-spacing-2)
--fs-checkbox-size	var(--fs-spacing-5)
--fs-checkbox-radius	var(--fs-spacing-1)
--fs-radio-size	var(--fs-spacing-5)
--fs-switch-width	var(--fs-spacing-10)
--fs-switch-height	var(--fs-spacing-6)
--fs-fieldset-gap	var(--fs-spacing-2)
--fs-search-icon-space	var(--fs-spacing-10)
--fs-search-icon-size	var(--fs-spacing-5)
--fs-toggle-group-radius	var(--fs-spacing-1)
--fs-toggle-group-height	var(--fs-spacing-10)
--fs-toggle-group-padding	0 var(--fs-spacing-4)
--fs-session-timeout-width	26rem
--fs-session-timeout-padding	var(--fs-spacing-5)
--fs-session-timeout-radius	var(--fs-spacing-1)
--fs-connection-status-layer	1000
--fs-connection-status-padding	var(--fs-spacing-2) var(--fs-spacing-4)

Standardverdiene peker på --fs-spacing-*-skalaen. Endrer du skalaen, følger komponentene med. Setter du variabelen, gjelder din verdi bare for den komponenten.

Når variabelen ikke rekker

Alt Fristil sender ut, både tokens og komponent-CSS, ligger i @layer fristil. CSS uten layer vinner alltid over CSS i et layer, uansett spesifisitet. Du kan derfor overstyre hva som helst med en enkel selektor:

.fs-button {
  letter-spacing: 0.02em;
}

Uten layeret ville du måttet slå selektorer som .fs-button[data-variant="danger"]:hover, eller ty til !important.

!important snur rekkefølgen

For erklæringer med !important går kaskaden motsatt vei: da vinner CSS inne i et layer over CSS utenfor. Skriver du !important for å være sikker, oppnår du det motsatte. Du trenger det ikke, så la det være.

display på dialogen

Ett unntak finnes, og det kommer av nettleseren og ikke av oss. En <dialog> uten open skjules av nettleserens eget stilark, og lagene sorterer bare innenfor ett opphav, så en hvilken som helst forfatterregel med display slår den skjulingen. Setter du display på .fs-dialog, blir en lukket dialog stående som et kort på siden. Ta da med regelen selv, minst like spesifikk som din egen:

dialog.fs-dialog:not([open]):not(:is(:popover-open)) {
  display: none;
}

Fristil setter selv display: flex når .fs-dialog__body er et direkte barn, slik at kroppen kan rulle, og har den regelen ved siden av.

Tailwind og lagrekkefølgen

Bruker du Tailwind, må laget vårt plasseres. Lagene teller i den rekkefølgen de først blir nevnt, og det siste vinner uansett spesifisitet. Sett rekkefølgen på første linje i CSS-en din:

@layer theme, base, fristil, components, utilities;

@import "tailwindcss";
@import "@fristil/designsystem/tokens.css";
@import "@fristil/designsystem/tailwind.css";

Uten den linja får du ett av to problemer, avhengig av hvilken import som kommer først:

Rekkefølge	Hva som skjer
fristil før base	Tailwinds Preflight nullstiller komponentene. Bakgrunnen forsvinner fra knappen.
fristil etter utilities	Komponentene slår Tailwind-klassene dine. p-6 på en .fs-button gjør ingenting.
base, fristil, utilities	Begge deler virker

Det første er testet, ikke antatt: tilpasning.browser.test.ts bygger det i sitt eget dokument og kontrollerer hva knappen faktisk får.

Fristils eget tema for Tailwind ligger i @fristil/designsystem/tailwind.css. Det er en vanlig CSS-fil, så pakken har ingen avhengighet til Tailwind, og din versjon er den eneste som er i bruk. Se Design tokens.

Ingen shadow DOM

Ingen komponent i Fristil bruker shadow DOM lenger. <fs-calendar> var den eneste, og den er fjernet til fordel for nettleserens eget datopanel. Se Dato i et skjema.

Det betyr at CSS-en din når fram overalt. Du trenger verken ::part() eller å lete etter en vei inn i en skyggerot.

Når CSS ikke er nok

Variabler og laget dekker utseendet. De dekker ikke at komponenten skal gjøre noe annet enn den gjør. Da kan du overta kildekoden til den ene komponenten:

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

Kommandoen kopierer komponentens filer inn i prosjektet ditt, og skriver om henvisningene ut av mappa, slik at kopien virker der den havner:

Kopierte button til src/ui/button/
  button.ts
  button.css

Komponenten er nå din. Oppdateringer av @fristil/designsystem rører den ikke.

Henvisninger ut av mappa peker nå på pakken:
  ../shared.js → @fristil/designsystem/shared

Bytt ut disse importene med kopien:
  @fristil/designsystem/button
  @fristil/designsystem/button.css

Klassenavnene følger med. Importerer du stilarket fra pakken i tillegg, finnes komponenten to ganger, og hvilken som vinner avgjøres av rekkefølgen. Bytt derfor ut importene, som utskriften sier.

Det du gir fra deg er oppdateringene. Rettelser og forbedringer i pakken treffer ikke kopien, og det er du som eier den derfra. Bruk kommandoen på den ene komponenten som trenger det, ikke på alle.

Tilgjengeligheten blir din. Testene våre kjører mot pakken, ikke mot kopien din, så en tilgjengelighetserklæring som viser til designsystemet dekker ikke en komponent du har overtatt og endret.

npx @fristil/designsystem overta uten navn lister komponentene. Kopien skrives ikke over hvis mappa finnes fra før, med mindre du legger til --overskriv=ja.