Kom i gang som utvikler

Designsystemet Punkt skal hjelpe deg som utvikler i Origo å komme raskt i gang med å bygge digitale løsninger som følger Oslo kommunes visuelle identitet og som er universelt utformet.

Koden til Punkt er delt opp i ulike pakker:

punkt-assets - Ikoner, fonter og logoer
punkt-css - Stilsett og -hjelpere for Punkts ressurser og komponenter
punkt-elements - Punkts Web Components-komponenter
punkt-react - Punkts React-komponenter
punkt-testing-utils - Verktøy for å forenkle enhetstesting

Minstekravet for å komme igang med Punkt er å installere assets og css. Deretter kan du velge om du trenger elements eller react.

assets, css og elements kan brukes fra vår CDN uten noen byggesteg, og det ønskes. Men de fleste velger å installere pakkene inn i sitt prosjekt. Se egne CDN-instrukser dersom du ønsker å bruke Punkt fra CDN. Alle andre instrukser forutsetter at du laster ned våre pakker fra NPM.

CSS og assets

Punkt CSS er basert på Sass, og for å få mest mulig utbytte av våre stilsett anbefaler vi at dere bruker SCSS-filene våre fremfor de genererte CSS-filene.

Start med å legge til de nødvendige pakker i prosjektet ditt:

npm add -D sass
npm add @oslokommune/punkt-assets
npm add @oslokommune/punkt-css

Deretter kan du inkludere Punkt i hoved-stilsettet ditt:

/* Overstyr stien til fontene. */
@use "@oslokommune/punkt-css/dist/scss/abstracts/variables" with (
  $font-path: "@oslokommune/punkt-assets/dist"
);

/* Hent inn Punkts stiler */
@use "@oslokommune/punkt-css/dist/scss/pkt";

Og vips er du i gang! Det er mulig du må fjerne noen av dine lokale stiler (f.eks. font-family) dersom de krasjer med Punkt.

Les mer om verktøyene og hjelpeklassene våre under de forskjellige Ressurser-sidene.

React

Vær oppmerksom på at Punkt React er avhengig av Punkt CSS. En del av våre React-komponenter tar internt i bruk komponenter fra Punkt Elements. Mer om dette lenger ned.

For å installere Punkt React:

npm add @oslokommune/punkt-react

Det er alt du strengt tatt trenger å gjøre. For instrukser om hvordan du tar i bruk komponentene og hva du kan gjøre med dem kan du lese på de enkelte komponenters dokumentasjonssider.

Eksempel:

import { PktButton, PktInput } from "@oslokommune/punkt-react";
...
<PktTextInput label="First name" id="firstName" />
<PktButton skin="primary" variant="icon-left" iconName="user">
	Testbutton
</PktButton>

OBS: Våre React-komponenter bruker ikoner og ressurser fra vår CDN. Dersom du bruker en Content Security Policy (CSP) må du åpne for å hente ressurser fra https://punkt-cdn.oslo.kommune.no/.

Dersom du har enhetstester i løsningen din kan det være at du må tilrettelegge litt spesielt for de React-komponenter som internt tar i bruk Punkt Elements. Sjekk komponentens dokumentasjon under avsnittene for “Implementasjon i kode” om du er usikker.

Elements

Punkt Elements er våre komponenter som er bygger på web components-teknologi. Det betyr at de kan tas i bruk i alle frontendrammeverk og til og med rett i HTML.

For å installere komponentene:

npm add @oslokommune/punkt-elements

Og deretter kan du finne instrukser for hver komponent under “Implementasjon i kode” på komponentens dokumentasjonsside.

Eksempel:

import @oslokommune/punkt-elements/dist/pkt-textinput.js;
import @oslokommune/punkt-elements/dist/pkt-button.js;

<pkt-textinput label="Fornavn" name="fornavn"></pkt-textinput>
<pkt-button type="submit"><span>Dette er en knapp</span></pkt-button>

Vær oppmerksom på at dersom du skal ha reaktivt innhold (innhold som kan forandre seg programmatisk) i komponentene anbefaler vi at det pakkes inn i en span eller div eller liknende.

CDN

Dersom du ønsker å ta i bruk CSS, ressurser og Elements-komponenter fra CDN kan det enkelt gjøres ved å inkludere disse rett inn i prosjektet ditt. Vær dog oppmerksom på at dersom du bruker CSP kan du støte på utfordringer. Legg inn https://punkt-cdn.oslo.kommune.no/ i CSP-reglene dine om så.

Vi anbefaler å enkelt og greit inkludere hele CSS-rammeverket vårt, men om du heller vil velge ut hva du ønsker å inkludere kan du finne rett fil ved å lete i vår CDN.

Her er et eksempel på hvordan du kan ta i bruk Punkt i en ren HTML-side:

<!doctype html>
<html lang="no">
  <head>
    <meta charset="utf-8" />
    <title>Punkt</title>
    <link
      href="https://punkt-cdn.oslo.kommune.no/latest/css/pkt.min.css"
      rel="stylesheet"
    />
    <script
      src="https://punkt-cdn.oslo.kommune.no/latest/elements/pkt-consent.js"
      type="module"
    ></script>
  </head>
  <body>
    <pkt-consent
      id="osloConsent"
      triggerType="link"
      triggerText="Åpne samtykkemodal"
      devMode
    ></pkt-consent>
    <script>
      const consent = document.querySelector("#osloConsent");
      consent.addEventListener("toggle-consent", (event) => {
        console.log(event.detail);
      });
    </script>
  </body>
</html>

Akkurat nå har vi en liten bug i Punkt Elements som gjør at for å få komponentene til å oppføre seg riktig fra CDN må du legge inn denne kodesnutten før du laster inn komponentene:

<script>
  // Workaround for "process is not defined" i nettlesermiljøer
  window.process = window.process || {};
  window.process.env = window.process.env || {};
  window.process.env.NODE_ENV = window.process.env.NODE_ENV || "production";
</script>

Trenger du hjelp?

Dersom du støter på noen problemer eller utfordringer må du ikke nøle med å ta kontakt med oss! Den enkleste måten å få kontakt med oss er på Slack-kanalen vår, men vi har også en epost-adresse du kan nå oss på: punkt@origo.oslo.kommune.no.