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. Alle andre stilark bygger på den, så den lastes først.

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.27.1/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.27.1/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å 90 kB, 11 kB over nettet 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.27.1/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 required-marker="symbol">
  <label>Fullt navn</label>
  <input class="fs-input" type="text" name="navn" required />
</fs-field>

Får du en tom side, har define-funksjonen nesten alltid ikke kjørt.

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, CssToken, Breakpoints, Containers

Hver komponent finnes også som eget inngangspunkt (@fristil/designsystem/button, /badge, /link og så videre) med en funksjon som heter det samme som komponenten.

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, data-*-attributtene, part-navnene, tokennavnene, --fs-*-variablene og oppføringene i exports er alle noe du kan bygge på, og de endres ikke uten en ny hovedversjon.

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