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 tokens

tokens.css definerer alle CSS-variablene. Alle andre stilark bygger på den, så den lastes først.

Med byggverktøy
Uten byggverktøy

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

<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>

Serverer du filene fra en CDN som støtter npm-pakker, bruker du stien @fristil/designsystem/tokens.css direkte.

Importer bare stilarkene du bruker. Det finnes ingen samlet CSS-fil, så en side med bare knapper laster ikke CSS for en datovelger.

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 egendefinerte elementer, og må registreres én gang når appen starter:

// main.ts, kjøres én gang
import "@fristil/designsystem/tokens.css"
import "@fristil/designsystem/field.css"
import { defineFsField } from "@fristil/designsystem/field"

defineFsField()

Flere kall er ufarlige, for funksjonen sjekker selv om elementet er registrert. Den gjør heller ingenting på en server, der det ikke finnes noen customElements å registrere i, så den 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/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, search.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 de egendefinerte elementene i JSX
`@fristil/designsystem/dom`	`setAttributes`: bruker et attributtsett på et element uten JSX
`@fristil/designsystem/field`	`defineFsField`, klassen `FsField`
`@fristil/designsystem/session-timeout`	`defineFsSessionTimeout`, klassen `FsSessionTimeout`
`@fristil/designsystem/connection-status`	`defineFsConnectionStatus`, klassen `FsConnectionStatus`
`@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`
`@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 et nytt hovedtall.

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
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