Kom i gang

Installer

npm install @fristil/designsystem

Pakken har ingen avhengigheter. Web-komponentene er vanlige HTMLElement-klasser, og ingenting registreres ved import alene, så en side som bare bruker CSS-komponentene tar ikke med noe JavaScript fra pakken. Tailwind-temaet er ren CSS, så pakken krever ingenting av Tailwind.

Importer stilarkene

tokens.css definerer alle CSS-variablene, og alle andre stilark bygger på den. Den må lastes, og står først i eksemplene av vane: rekkefølgen mellom den og de andre har ikke noe å si.

Med byggverktøy

Ett stilark per komponent, med tokens.css først:

// main.js eller main.ts, øverst
import "@fristil/designsystem/tokens.css"
import "@fristil/designsystem/button.css"

Eller alt i én import, uten å velge:

import "@fristil/designsystem/fristil.css"

fristil.css har tokens.css og alle komponentstilarkene i seg, så den erstatter hele lista. Tailwind-temaet står utenfor, og hører ikke i en JavaScript-import i det hele tatt: tailwind.css er en @theme-blokk Tailwinds egen kompilator må lese, og settes opp som en @import i din egen CSS. Se Tailwind.

Uten byggverktøy

Én fil med alt, én rundtur:

<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fristil/designsystem@0.36.0/dist/fristil.css" />
</head>

Eller bare det du bruker:

<head>
  <link rel="stylesheet" href="/node_modules/@fristil/designsystem/src/tokens/tokens.css" />
  <link rel="stylesheet" href="/node_modules/@fristil/designsystem/src/components/css/button/button.css" />
</head>

Uten et byggesteg henter noen av stilarkene delene sine med @import, som nettleseren først ser når fila er lastet. dist/fristil.css har alt flatet ut, uten @import, og er derfor det raskeste valget når du lenker. Fra en CDN skriver du den virkelige stien i pakken, altså @fristil/designsystem@0.36.0/src/tokens/tokens.css. Korte navn som @fristil/designsystem/tokens.css er oppføringer i exports, og dem er det bare et byggesteg som leser.

Lenker du uten byggesteg, bruk fristil.css. Én rundtur på 103 kB, 13 kB komprimert med gzip, og ingen @import nettleseren må laste fila for å oppdage. Lista med ett stilark per komponent er for den som har et byggesteg: der laster en side med bare knapper ikke CSS for en dialog. «Ren HTML»-fanen på hver komponentside oppgir lenkene til de enkelte stilarkene, siden lista samtidig sier hva komponenten krever, og fristil.css dekker hver av dem.

Første komponent

Med tokens.css og button.css importert:

Eksempel

Kode

<button class="fs-button">Send søknad</button>
<button class="fs-button" data-variant="secondary">Lagre utkast</button>

Ingen registrering, ingen oppstartskode. CSS-komponentene er bare klasser.

Registrer web components

Ramme- og frittstående komponenter er web components, og må registreres én gang når appen starter. defineFs() registrerer alle ni:

// main.ts, kjøres én gang, ved import og ikke i en effekt
import "@fristil/designsystem/tokens.css"
import "@fristil/designsystem/field.css"
import { defineFs } from "@fristil/designsystem/register"

defineFs()

Uten byggverktøy peker du på den bygde fila:

<script type="module">
  import { defineFs } from "https://cdn.jsdelivr.net/npm/@fristil/designsystem@0.36.0/dist/register.js"
  defineFs()
</script>

Kallet skal skje så tidlig som mulig, før noe rendres og aldri i en useEffect. Et element som står i siden før registreringen er et vanlig HTMLElement uten oppførsel, og et metodekall på det i det gapet feiler. Hjelperne showToast, reportFailure, reportSuccess, extendSession og resetSession venter i stedet på registreringen og utfører kallet når den kommer. Registreringen drar koden til alle ni med seg. Bruker du én av dem, kall dens egen funksjon i stedet, som defineFsField() fra @fristil/designsystem/field.

Flere kall er ufarlige, for funksjonene sjekker selv om elementet er registrert. De gjør heller ingenting på en server, der det ikke finnes noen customElements å registrere i, så de kan stå i en fil som kjøres begge steder.

<fs-field>
  <label class="fs-label" for="navn" data-required="symbol">Fullt navn</label>
  <input class="fs-input" id="navn" type="text" name="navn" required />
  <p class="fs-help-text">Slik det står i passet.</p>
</fs-field>

Står ledeteksten, feltet og hjelpeteksten der, men hjelpeteksten er ikke koblet til feltet med aria-describedby, har define-funksjonen ikke kjørt. Markupen i en ramme-komponent er din og vises uansett, med to unntak: Tabs viser bare det første panelet, og Suggestion skjuler lista, til de er registrert, siden de ellers hopper når skriptet kommer. Feiler skriptet, når brukeren ikke de andre fanene. Det er bare de to frittstående, <fs-toast> og <fs-connection-status>, som er tomme til de er registrert. Et <fs-session-timeout> viser ingenting før varselet skal komme, og uten registrering kommer det aldri.

Inngangspunkter

Stilark

Hver komponent har sitt eget stilark, oppkalt etter siden sin: @fristil/designsystem/button.css, /checkbox.css, /table.css og så videre. Importer dem du bruker.

Import	Innhold
@fristil/designsystem/fristil.css	Alt i én fil: tokens og hver komponent, uten @import. Ikke Tailwind-temaet
@fristil/designsystem/tokens.css	Alle CSS-variabler. Kreves av alt annet.
@fristil/designsystem/<komponent>.css	Én komponent, med samme navn som siden dens
@fristil/designsystem/sr-only.css	.fs-sr-only, tekst bare skjermlesere får
@fristil/designsystem/tailwind.css	Fristils verdier som Tailwind-tema. Valgfri, se Tailwind.

Noen stilark samler det de trenger, så du slipper å importere delene hver for seg: field.css, error-summary.css, fieldset.css, search.css, session-timeout.css og suggestion.css.

Alle web-komponentene trenger et stilark. Ingen av dem bruker shadow DOM, så elementene er alminnelige elementer med systemets klasser, og klassene må lastes på siden.

JavaScript og TypeScript

Hele komponent-API-et ligger i ett navnerom:

import { fs } from "@fristil/designsystem"

fs.button({ variant: "secondary" })
fs.input({ type: "email", state: "invalid" })
fs.badge({ color: "success" })

Skriv fs. i editoren, så ser du hva som finnes. Bruker du React, importer fra @fristil/designsystem/react. Kallene er de samme, men returverdien bruker className og htmlFor. Se Typesikker bruk.

Import	Innhold
@fristil/designsystem	fs med alle komponentene, alle typene, og web component-registreringene
@fristil/designsystem/react	Samme fs, men med className og htmlFor
@fristil/designsystem/react-jsx	Typer for web components i JSX
@fristil/designsystem/dom	setAttributes: bruker et attributtsett på et element uten JSX
@fristil/designsystem/register	defineFs: registrerer alle web-komponentene i ett kall
@fristil/designsystem/diagnostics	diagnoseMarkup: sjekker HTML mot elementene og klassene, som editoren gjør. Se Editoren
@fristil/designsystem/field	defineFsField, klassen FsField
@fristil/designsystem/session-timeout	defineFsSessionTimeout, klassen FsSessionTimeout, extendSession og resetSession
@fristil/designsystem/connection-status	defineFsConnectionStatus, klassen FsConnectionStatus, reportFailure og reportSuccess
@fristil/designsystem/tabs	defineFsTabs, klassen FsTabs
@fristil/designsystem/error-summary	defineFsErrorSummary, klassen FsErrorSummary
@fristil/designsystem/popover	defineFsPopover, klassen FsPopover
@fristil/designsystem/toast	defineFsToast, klassen FsToast, showToast
@fristil/designsystem/suggestion	defineFsSuggestion, klassen FsSuggestion
@fristil/designsystem/dialog	defineFsDialog, klassen FsDialog
@fristil/designsystem/field-core	computeFieldAttributes: det fs.field og <fs-field> deler
@fristil/designsystem/host-element	HostElement og defineElement: grunnlaget web-komponentene arver fra
@fristil/designsystem/tokens	cssTokens, colorTokens, darkColorTokens, darkTokens, typene CssToken, ColorToken, Breakpoint og Container, Breakpoints, Containers, og hva fargefamiliene, rollene og lagene er til

Hver CSS-komponent finnes også som eget inngangspunkt (@fristil/designsystem/button, /badge, /link og så videre) med en funksjon som heter det samme som komponenten. Unntaket er /switch, der funksjonen heter switchControl, siden switch er et reservert ord. Byggefunksjonene for web-komponentene, som fs.tabs() og fs.dialog(), har ikke eget inngangspunkt: de ligger i fs og i hovedinngangen. /tabs, /dialog og de andre har klassen og define-funksjonen.

fs er valgfritt. class="fs-button" data-variant="secondary" for hånd gir samme resultat; funksjonene finnes for å fange skrivefeil.

Versjoner

Pakken følger semantisk versjonering. Det offentlige API-et er større enn funksjonene: klassenavnene, attributtene byggefunksjonene skriver (data-* og aria-* medregnet), tokennavnene, --fs-*-variablene og oppføringene i exports er alle noe du kan bygge på.

Før 1.0 kan et nytt undertall, som et skifte fra 0.x til 0.(x+1), ha brytende endringer. De står da under overskriften «Brytende» i versjonsloggen, med hva du må endre. Fra 1.0 endres ingen av disse uten en ny hovedversjon.

npm install skriver versjonen med ^ foran. Under 1.0 godtar ^ bare nye rettelser i det samme undertallet, så et nytt undertall får du først når du ber om det, ved å skrive det nye nummeret i package.json eller installere pakken på nytt.

Pakken er ren ESM, uten CommonJS-utgave. Bruk import.

Hva som er endret i hver versjon står i CHANGELOG.md, som også følger med i pakken.

Videre

• Rammeverk: konkret oppsett for ren HTML, React, Astro og Datastar
• Editoren: fullføring og feilmeldinger i VS Code og JetBrains, også uten TypeScript
• Design tokens: hvilke variabler som finnes, og hva de heter
• Tailwind: oppsett og Fristils verdier som utility-klasser
• Button: den enkleste komponenten å begynne med
• Mønstre: hele skjemaer, lister og sider satt sammen