Ordbok
Forklaringer på fagbegreper som brukes i dokumentasjonen. Begreper er lenket til herfra der de første gang dukker opp i en ADR eller annen tekst.
- axe-core
axe-core er et open source-bibliotek fra Deque Systems som analyserer DOM-en og rapporterer brudd på tilgjengelighetsregler (WCAG). I Indeks kjøres axe-core via Playwright mot WCAG 2.2 A og AA — violations blokkerer merge.
- CDN
Content Delivery Network. Et nettverk av servere plassert geografisk nær brukeren som leverer statiske filer (CSS, JS, bilder) raskere enn en sentralisert server. Indeks publiserer CSS og Web Components til CDN med versjonerte URLer — f.eks. `cdn.sparebank1.no/indeks/css/1.2.3/index.css`. Versjonerte URLer kan caches "for alltid" i nettleseren.
- Changesets
Changesets er et verktøy for monorepoer der bidragsytere beskriver endringer i egne filer (`.changeset/`). Disse filene akkumuleres til en release-PR automatisk konfigurerer versjonsnumre og endringslogg. I Indeks erstatter Changesets det eldre Lerna + Conventional Commits-opplegget — og krever ikke spesifikt commit-format.
- CMS
Content Management System. Et system som lar redaktører og innholdsprodusenter publisere og redigere innhold uten å gå direkte i kode. Indeks-dokumentasjonen bruker foreløpig Docusaurus (markdown/MDX) i stedet for CMS — migrering til CMS venter på avklaringer med merkevare og redaktørene.
- CSS custom properties
CSS custom properties (også kalt CSS-variabler) er verdier definert med `--`-prefiks, f.eks. `--ix-spacing-md` eller `--ix-color-fill-main-default`. De kan settes og overskrives i runtime med JavaScript eller ved å legge CSS-klasser på et container-element. I Indeks er alle design tokens eksponert som CSS custom properties.
- CSS Modules
CSS Modules er en build-mekanisme der klassenavn automatisk gjøres unike per fil — f.eks. blir `.button` til `.button_a3f2c_1`. Det løser navnekollisjoner, men genererer hash-baserte klassenavn som er vanskelige å dokumentere og bruke fra utsiden. Indeks bruker `ix-`-prefiks i stedet for CSS Modules for å unngå dette.
- CSS-in-JS
CSS-in-JS er en tilnærming der styling defineres i JavaScript eller TypeScript, typisk med biblioteker som styled-components, Emotion eller vanilla-extract. Fordelen er tett kobling mellom komponent og stil. Ulempene er runtime-overhead (for de fleste bibliotekene), binding til React, og at CSS-only-bruk blir umulig. Indeks bruker ren CSS.
- Custom Elements API
Custom Elements API er en del av Web Components-standarden. Det lar utviklere registrere egne HTML-elementer (`customElements.define('ix-field', IxField)`) med tilhørende klasse og livssyklus-metoder. Elementene fungerer i alle moderne nettlesere uten ekstra rammeverk.
- density-system
Density-systemet lar konsumenter velge mellom tre tettheter: Compact (nettbank/bedrift), Default og Comfortable (salgssider/markedsføring). Det styres med CSS-klasser på et container-element (`.ix-density--compact` osv.) og er implementert som et fast skift på ±2 trinn i spacing-skalaen. Alle komponenter inni container-elementet arver valgt density.
- design tokens
Design tokens er navngitte designbeslutninger — farger, spacing, typografi, border-radius osv. — lagret som data (JSON i Indeks) og distribuert til web (CSS custom properties), iOS (Swift) og Android (XML). Tokens har to nivåer: primitive tokens (f.eks. `brand-550`) og semantiske tokens (f.eks. `color-fill-main-default`) som peker på primitiver.
- Docker
Docker er en plattform for containerisering. En container pakker applikasjonen med alle avhengigheter slik at den kjører likt uavhengig av operativsystem. I Indeks brukes Docker for Playwright-tester fordi screenshot-resultater varierer mellom macOS og Linux — Docker sikrer at CI og lokal utvikling bruker identisk miljø.
- Docusaurus
Docusaurus er et open source-rammeverk fra Meta for å bygge dokumentasjonssider. Det er Markdown/MDX-basert, støtter versjonert dokumentasjon og er enkelt å komme i gang med. Indeks bruker Docusaurus som midlertidig dokumentasjonsplattform inntil en CMS-løsning er på plass.
- ESM
ES Modules (ESM) er det moderne JavaScript-modulsystemet, introdusert i ES2015. Moduler eksporteres med `export` og importeres med `import`. ESM er nødvendig for tree-shaking og støttes nativt i alle moderne nettlesere og Node.js. Indeks distribuerer kun ESM — ikke det eldre CommonJS-formatet.
- fluid skalering
Fluid skalering betyr at verdier (spacing, typografi) skalerer kontinuerlig med viewport-bredden via CSS `clamp()` — i stedet for å "hoppe" ved faste breakpoints. I Indeks skalerer basen fra 16px (375px viewport) til 18px (1024px+), og alle tokens beregnes fra denne basen med en geometrisk skala.
- HSL
HSL er et fargerom der farger beskrives med fargetone (Hue), metning (Saturation) og lysstyrke (Lightness). Det er intuitivt for mennesker, men ikke perseptuelt uniform — blå og gul med identiske L-verdier oppleves som ulike lysheter. Dette gjør det vanskelig å generere konsistente fargeskalaer. Indeks bruker OKLCH i stedet.
- MDX
MDX er en utvidelse av Markdown som lar deg bruke React-komponenter direkte i teksten. I Indeks-dokumentasjonen brukes MDX bl.a. til å vise `AdrStatusLogg`, `AdrDeltakere` og interaktive komponenteksempler. MDX-filer kompileres av Docusaurus og kan importere komponenter som vanlige React-filer.
- Monorepo
Et monorepo er ett git-repository som inneholder flere pakker eller prosjekter. Det gjør det enkelt å koordinere endringer på tvers av pakker og sikrer at interne avhengigheter alltid er i sync. Indeks er et monorepo med pnpm workspaces og Turborepo for build-orkestrering.
- npm provenance
npm provenance er en mekanisme der publiserte pakker signeres med kryptografisk bevis på at de ble bygget av en spesifikk GitHub Actions-kjøring fra en spesifikk commit i et spesifikk repo. Konsumenter kan verifisere at pakken faktisk kommer fra kildekoden og ikke er manipulert. Indeks publiserer alle pakker med provenance.
- OKLCH
OKLCH er et moderne fargerom der farger beskrives med Lightness (L), Chroma (C) og Hue (H). Det er perseptuelt uniformt — lik L-verdi gir lik opplevd lysstyrke uavhengig av fargetone. Dette gjør det mulig å generere hele fargeskalaer fra én nøkkelfarge og få forutsigbare kontraster. Indeks genererer alle fargeskalaer med OKLCH ved build.
- peer dependency
En peer dependency er en avhengighet som pakken trenger for å fungere, men som ikke er bundlet inn i pakken selv — konsumenten forventes å ha den installert. F.eks. deklarerer `@sb1/indeks-react` React som peer dependency (`"react": "^19.0.0"`). Det sikrer at konsumenten bruker sin egen React-instans og ikke får duplisert React i bunten.
- perseptuelt uniform
Et fargerom er perseptuelt uniformt når lik numerisk avstand mellom verdier tilsvarer lik opplevd visuell forskjell for menneskeøyet. HSL er ikke perseptuelt uniform — blå og gul med identiske S/L-verdier oppleves ulikt. OKLCH er designet for å være perseptuelt uniform og gir dermed mer forutsigbare og konsistente fargeskalaer.
- Playwright
Playwright er et testrammeverk fra Microsoft for end-to-end og visuell regresjonstesting. Det støtter Chromium, Firefox og WebKit. I Indeks kjøres Playwright i Docker mot Storybook for å ta og sammenligne screenshots — og for å kjøre axe-core-basert tilgjengelighets-testing mot WCAG 2.2.
- pnpm
pnpm er en pakkebehandler for Node.js. Den skiller seg fra npm ved at pakker lagres i et content-addressable globalt lager og lenkes inn per prosjekt — det sparer diskplass og gir raskere installasjon. I tillegg håndhever pnpm streng isolasjon (`shamefully-hoist=false`) slik at pakker bare kan bruke avhengigheter de eksplisitt har deklarert.
- PostCSS
PostCSS er et verktøy som transformerer CSS via plugins. Det brukes bl.a. til å kompilere moderne CSS-syntaks (f.eks. nesting, `color-mix()`) for eldre nettlesere, legge til vendor-prefikser med autoprefixer, og erstatte imports med absolutte URL-er for CDN-bygg. Indeks leverer ferdig PostCSS-kompilert CSS — konsumenter trenger ikke kjøre PostCSS selv.
- semantisk mapping
Semantisk mapping er koblingen fra primitive tokens (f.eks. `brand-550`) til semantiske tokens som beskriver bruksområde (f.eks. `color-fill-main-default`). De semantiske tokenene varierer mellom light og dark mode — i light mode peker `color-fill-main-default` på `brand-550`, i dark mode på `brand-450`. Designerne eier den semantiske mappingen i Figma.
- Shadow DOM
Shadow DOM er en del av Web Components-standarden som lar en komponent ha sin egen isolerte DOM-tre og CSS — atskilt fra resten av dokumentet. Det gir sterk innkapsling, men gjør tilgjengelighetsarbeid vanskeligere fordi ARIA-relasjoner ikke kan krysse shadow boundaries. Indeks unngår Shadow DOM som hovedregel av denne grunn.
- SSR
Server-Side Rendering betyr at HTML genereres på serveren (f.eks. i Node.js) og sendes ferdig rendret til klienten. Det gir raskere første rendering og bedre SEO. Web Components bruker `customElements.define()` som er en nettleser-API og ikke finnes i Node.js — SSR-støtte for Indeks Web Components er derfor et åpent spørsmål som adresseres per komponent.
- Storybook
Storybook er et open source-verktøy for isolert komponentutvikling. Komponenter bygges og demonstreres i "stories" uten å måtte kjøre hele applikasjonen. Indeks bruker Storybook 9 med a11y- og docs-addons, og publiserer det til design.sparebank1.no/storybook. Playwright-tester kjøres mot Storybook.
- theming
Theming i Indeks betyr at konsumenter (f.eks. Kredittbanken eller Spleis) kan definere egne nøkkelfarger og få komplette OKLCH-fargeskalaer og semantiske tokens generert for sitt tema. Fordi OKLCH er perseptuelt uniformt, fungerer de semantiske mappingene (f.eks. hvilke trinn som brukes for tekst og bakgrunn) likt for alle fargetoner.
- tree-shaking
Tree-shaking er en optimaliseringsteknikk i moderne bundlere (Vite, webpack, Rollup) der ubrukt kode fjernes fra finalpakken. Det krever ESM-format (ikke CommonJS) fordi ESM har statisk analyserbar import/export-struktur. Indeks distribueres som ESM-only nettopp for å muliggjøre effektiv tree-shaking hos konsumenter.
- Turborepo
Turborepo er et build-system for monorepoer som bygger pakker i riktig rekkefølge basert på dependency-grafen og cacher resultater basert på innholdshasher av kildefiler. Hvis ingenting har endret seg siden forrige bygg, hoppes pakken over. Det gjør CI raskere og unngår unødvendige rebuilds under lokal utvikling.
- utility-klasser
Utility-klasser er CSS-klasser med ett ansvarsområde — f.eks. `ix-flex` for `display: flex` eller `ix-m-md` for `margin: var(--ix-spacing-md)`. De brukes direkte i HTML og dekker de fleste layoutbehov. For avanserte behov (egne komponenter, theming) brukes CSS custom properties direkte. Tilnærmingen ligner Tailwind, men er basert på Indeks sine egne tokens og `ix-`-prefix.
- Vite
Vite er et moderne build-verktøy for frontend med en rask dev server basert på native ESM og Rollup for produksjonsbygg. Library mode gjør det enkelt å bygge komponentbiblioteker med TypeScript-declarations. Indeks bruker Vite for alle library-pakker og Storybook bruker Vite som builder.
- WCAG
WCAG (Web Content Accessibility Guidelines) er internasjonale retningslinjer for tilgjengelighet på web, utgitt av W3C. De er organisert i tre nivåer: A (minimum), AA (anbefalt standard) og AAA (høyeste nivå). Indeks tester automatisk mot WCAG 2.2 A og AA via axe-core i Playwright — violations blokkerer merge.
- Web Components
Web Components er en samling webstandarder (Custom Elements, Shadow DOM, HTML Templates) som lar utviklere lage gjenbrukbare custom HTML-elementer (`<ix-field>`) som fungerer i alle nettlesere uten avhengighet til React eller andre rammeverk. Indeks implementerer komponentlogikk som Web Components i `indeks-web` og eksponerer dem til React via tynne wrappers i `indeks-react`.