Farger for Web

Pakken @sb1/indeks-tokens inneholder fargetokens som brukes i hele designsystemet. På web trenger de aller fleste ikke å generere farger selv — den ferdig bygde CSS-en inneholder alt du trenger. Men du kan generere din egen web-CSS med et eget theme ved hjelp av den samme build-colors-kommandoen som brukes for native (iOS/Android).

Standard bruk: importer ferdig CSS

I de aller fleste tilfeller skal du ikke generere farger selv. Bruk den ferdig bygde CSS-en, som allerede inneholder alle fargetokens:

@import url('https://cdn.sparebank1.no/indeks/css/<versjon>/index.css');

Eller via npm med @sb1/indeks-css (som inkluderer tokens):

npm install @sb1/indeks-css

Da får du alle --ix-color-*-variablene ferdig satt opp med både light og dark mode. Du trenger ikke resten av denne siden.

Egen web-CSS fra eget theme

Har du behov for et eget theme (egne merkevarefarger), kan du generere web-CSS med build-colors:

npx @sb1/indeks-tokens build-colors platform=web path=./css theme=./my-theme.json

Uten theme= genereres CSS-en med standard sb1-theme.

Output

Kommandoen skriver to slags filer til path:

css/
├── colors.css
└── themes/
    └── <theme-navn>.css

• themes/<theme-navn>.css — primitivene (--ii-primitive-*), altså de fullstendige fargeskalaene generert fra basisfargene i themet ditt. Merk at basisfargen kun styrer fargetone og metning — lysheten settes per trinn, så å gjøre en basisfarge lysere eller mørkere endrer ikke skalaen.
• colors.css — de semantiske fargene (--ix-color-*), som peker inn i primitivene. Denne inneholder både light mode (:root, .ix-light-mode), dark mode (.ix-dark-mode) og prefers-color-scheme-håndtering.

--ii- vs --ix-

--ii-primitive-* er interne primitiver (implementasjonsdetalj) — ikke bruk dem direkte i applikasjonskoden din. --ix-color-* er det offentlige API-et du styler mot.

Rekkefølge og overstyring

Importér begge de genererte filene. Rekkefølgen dem imellom spiller ingen rolle — --ix-color-* refererer til --ii-primitive-* via var(), og CSS custom properties slås opp når de brukes, uavhengig av import-/deklarasjonsrekkefølge:

@import './css/themes/my-theme.css';
@import './css/colors.css';

Bruker du både @sb1/indeks-css (for komponent-CSS) og ditt eget theme, er det derimot rekkefølgen mot indeks-css som avgjør. Den ferdige CSS-en inlirer de samme tokenene under nøyaktig samme selektorer og spesifisitet, og det finnes ingen @layer som skiller dem — så det er «sist vinner» som gjelder:

@import url('https://cdn.sparebank1.no/indeks/css/<versjon>/index.css');
@import './css/themes/my-theme.css';
@import './css/colors.css';

Eget theme må lastes sist

Ditt eget theme overstyrer bare indeks-css hvis det importeres etter indeks-css. Lastes det før — eller uten kontroll på rekkefølgen i bundleren — vinner indeks-css, og temaet får stille ingen effekt.

Generere farger i runtime

Trenger du å endre farger on-the-fly — typisk å bytte brand-fargen basert på brukervalg eller merkevare — kan du generere fargeskalaer i runtime, både i nettleseren og i en Node-backend. Da bruker du subpath-eksporten @sb1/indeks-tokens/generate.

Da blir @sb1/indeks-tokens en ekte avhengighet

Ved standard bruk (ferdig CSS) trenger du bare @sb1/indeks-css. Men bruker du runtime-API-et, importerer applikasjonskoden din faktisk JavaScript fra @sb1/indeks-tokens — da må pakken ligge under dependencies (ikke devDependencies) i din package.json:

npm install @sb1/indeks-tokens

Fargematematikken (colorjs.io) er bundlet inn i eksporten, så du får ingen ekstra avhengigheter å forholde deg til.

Slik henger det sammen

De semantiske fargetokenene (--ix-color-*) peker på primitivene via var(--ii-primitive-*). For å rethem-e i runtime trenger du derfor bare å regenerere primitiv-skalaen for de(n) basisfargen(e) du vil endre og sette --ii-primitive-<navn>-<steg> på et scope — alle de semantiske tokenene re-resolver seg selv via var()-kaskaden. Du skal aldri regenerere det semantiske laget selv.

Eneste tillatte bruk av --ii-

--ii-primitive-* er ellers interne (se over). Runtime-generering er det ene stedet der du bevisst setter dem. API-et eier navnekonvensjonen og gray-0 = #FFFFFF-unntaket for deg, så du slipper å hardkode dem.

API

• buildColorScaleVariables(navn, farge) — bygger en 20-trinns skala fra én basisfarge og returnerer en ferdig CSS-variabel-map: { '--ii-primitive-brand-0': '#…', … }.
• applyColorScaleVariables(element, variabler) — setter map-en som inline-styling på et element (nettleser).
• colorScaleVariablesToCss(variabler, { selector }) — serialiserer map-en til en CSS-streng (Node-backend / injeksjon i <head>). selector er valgfri, standard :root.

De to hjelperne tar en variabel-map, så du kan slå sammen flere skalaer: { ...buildColorScaleVariables('brand', a), ...buildColorScaleVariables('info', b) }.

I nettleseren

import { buildColorScaleVariables, applyColorScaleVariables } from '@sb1/indeks-tokens/generate';

const vars = buildColorScaleVariables('brand', '#E4002B');
applyColorScaleVariables(document.documentElement, vars);
// Alle --ix-color-* som bygger på brand oppdateres nå automatisk.

Vil du se det i praksis — skriv inn en basisfarge og se hele appen rethem-e seg live:

Prøv fargegenerering i eksempelappen →

I en Node-backend

Generér en CSS-streng du kan sende til klienten (f.eks. injisert i <head>):

import { buildColorScaleVariables, colorScaleVariablesToCss } from '@sb1/indeks-tokens/generate';

const vars = buildColorScaleVariables('brand', '#E4002B');
const css = colorScaleVariablesToCss(vars);
// ':root {\n  --ii-primitive-brand-0: #…;\n  … \n}'

// Vil du scope temaet til et delområde i stedet for hele siden:
const scoped = colorScaleVariablesToCss(vars, { selector: '.min-merkevare' });

Se Fargeskalaer for hva basisfargen faktisk styrer (fargetone og metning — ikke lyshet).

Eksempel på egen theme-fil

Theme-fila er en JSON-fil med de sju basisfargene. identityColor og themeable (font, border-radius) er valgfrie. Lag en fil my-theme.json:

{
    "name": "my-custom-theme",
    "identityColor": "#005aa4",
    "colors": {
        "brand": "#0078D8",
        "success": "#00885B",
        "info": "#467CA4",
        "danger": "#C94E4F",
        "warning": "#AF6500",
        "gray": "#6D7888",
        "neutral": "#AF6516"
    },
    "themeable": {
        "font-family": {
            "normal": "Inter, sans-serif",
            "heading": "Inter, sans-serif"
        }
    }
}

Filnavnet på theme-CSS-en følger name-feltet i JSON-fila — themet over gir css/themes/my-custom-theme.css.

Parametere

• platform=web — spesifiserer at du vil bygge web-CSS
• path=<sti> — hvor filene skal lagres (f.eks. ./css)
• theme=<sti> — (valgfri) sti til egen JSON-theme-fil (default: sb1)

Den samme kommandoen bygger også farger for iOS og Android — se Farger for Native.