Bidra med kode

Grunnleggende oppsett

Forutsetninger

  • nodejs 20.19 eller nyere
  • Kunnskap om Sass (SCSS) og CSS.
  • Forståelse av BEM-navnekonvensjoner som designsystemet følger.
  • Noen skal ha designet ditt bidrag i Figma (Krever innlogging og tilgang) dersom du bidrar med ny funksjonalitet.

Aller først må du konfigurere git-hooks slik at scripts kjøres ved commits, som for eksempel et script som kopierer innhold fra readme og contributing til dokumentasjonsnettsiden.

Sett opp git hooks:

git config core.hooksPath scripts/git-hooks

Utviklingsmiljøet

Vi bruker Lerna for å gjøre utvikling i et monorepo smidigere. Vi har en rekke kommandoer du kan kjøre fra rotkatalogen i vårt repo. Her er de du gjerne vil forholde deg til som bidragsyter til Punkt:

npm run build            # Bygger alle pakkene og docs. Greit for å teste før push.
npm run dev-css          # Kjører punkt-css dev-serveren
npm run dev-docs         # Kjører docs dev-serveren
npm run dev-react        # Kjører punkt-react dev-serveren
npm run svgo             # Optimaliserer svg-filer i gitte foldere i assets
npm run test-react       # Kjører tester i React-pakken
npm run test-testutils   # Kjører tester i punkt-testing-utils
npm run watch-css        # Lytter til endringer i SCSS-filer og bygger CSS

Lag PR

Når du er klar for en PR skriv din GitHub-message som sier hva som er gjort, og evt issue nummer.

Vi bruker Conventional Commits for å beskrive commits gjennom noen regler. Ingen fare om du ikke følger den, vi tar en gjennomgang og evt justerer.

<type>(<omfang>): #<oppgavenummer> <beskrivelse>

[valgfri ytterligere beskrivelse av endringen]

Type

  • feat: En ny funksjon
  • fix: En feilretting
  • docs: Kun endringer i dokumentasjon - vår nettside
  • chore: Endringer i byggeprosessen eller hjelpeverktøy og biblioteker
  • style: Endringer som ikke påvirker betydningen av koden (mellomrom, formatering, osv)

Omfang

  • assets (@oslokommune/punkt-assets på NPM)
  • elements (@oslokommune/punkt-cli på NPM)
  • css (@oslokommune/punkt-css på NPM)
  • react (@oslokommune/punkt-react på NPM)
  • all (alle ovennevnte)

OBS: Pakker som avhenger av pakkene du endrer vil også påvirkes og publiseres i ny versjon.

Oppgavenummer

GitHub oppgavenummer som denne commit er relatert til.

Beskrivelse

En kort beskrivelse av endringen.

Ytterligere beskrivelse og breaking changes (valgfri)

En lengre beskrivelse av endringen, kan være flere avsnitt. Dersom koden din inneholder breaking changes må du starte denne meldingen med BREAKING CHANGE. Dette vil forårsake en bump til ny major-versjon for Punkt.

Eksempler

fix(react): #NR Rett feil på alert-komponenten    # med issuenummer
fix(react): Rett feil på alert-komponenten        # patcher en bug i koden (patch i Semantic Versioning)
feat(react): Legg til funksjonalitet              # ny funksjonalitet i koden (minor i Semantic Versioning)
docs: Ny tekst på bidra-siden                     # Endring i dokumentasjon

Bugs

Hvis du finner en bug sjekk om den allerede diskuteres på Github discussion. Hvis ikke kan du opprette et issue her.

Nye ideer?

Hvis du vil diskutere nye features eller muligheten for å endre på eksisterende funksjonalitet++, dra hit. Tag gjerne diskusjonen du lager med en av de eksisterende kategoriene.

Hvis diskusjonen ender med at arbeid på designsystemet skal utføres, så lager vi (Origo) et issue, som lenker til diskusjonen. Hvis deler av arbeidet skal utføres på noe som eksisterer i dette repoet, så skal det også opprettes en PR i det oppgaven påbegynnes - ikke i det den er ferdig!

Stilendringer

Bli kjent med koden

@oslokommune/punkt-css
├── dist/                          # Distribusjonsversjonen av pakken
|   ├── css/                       # OBS! Generert css
|   |   ├── components/            # hver komponent separat
|   |   |   ├── alert.css          # komponent alert
|   |   |   └── ...
|   |   ├── elements/              # hvert HTML-element separat
|   |   |   ├── button.css         # elementet button
|   |   |   └── ...
|   |   ├── pkt.css                # alle moduler
|   |   ├── pkt.min.css            # alle moduler minimert
|   |   ├── pkt-base.css           # base modul
|   |   ├── pkt-base.min.css       # base modul minimert
|   |   ├── pkt-components.css     # komponent modul med alle komponenpkt
|   |   ├── pkt-components.min.css # komponent modul minimert
|   |   ├── pkt-elements.css       # element modul
|   |   ├── pkt-elements.min.css   # element modul minimert
|   |   ├── pkt-normalise.css      # normalisering modul
|   |   └── pkt-normalise.min.css  # normalisering modul minimert
|   └── scss/                      # css-rammeverket med dets moduler
├── CHANGELOG.md                   # alle nevneverdige endringer
├── index.js                       # peker på komplett rammeverk
├── LICENSE                        # MIT lisens
├── package.json                   # all info om prosjektet
└── README.md                      # kom i gang-informasjon

SCSS

Skal du jobbe med CSS-rammeverket er dette stedet å starte.

scss
├── abstracts/        # Variabler, funksjoner, mixins: Sass-verktøy som ikke generer CSS.
|   ├── functions/    # Kodeblokker som returnerer enkeltverdier av en eller annen Sass data type.
|   ├── mixins/       # Kodeblokker som genererer Sass kode som igjen kompilerer til CSS-stiler.
|   ├── placeholders/ # Lik class selectors som ikke genereres uten at de er tatt i bruk (extended).
|   └── variables/    # Variabler eller design tokens som de kalles er fundamentet til rammeverket.
├── base/             # Grunnleggende moduler som farger, grid, fonter, tekststiler, mm.
├── components/       # Både enkle og mer komplekse komponenter. Grunnlag for komponent-bibliotekene.
├── elements/         # HTML-elementer som er stylet, som knapper, lister og tabeller.
└── normalise/        # En ganske liten normalisering for å ha en felles baseline.

Abstracts består av konfigurasjonen og hjelpeverktøyene til CSS-rammeverket. Ingenting under denne folderen skal generere en eneste linje CSS når den er kompilert på egen hånd.

Folderen /variables er en samling Sass-variabler skrevet på formen Sass maps. Dette gir en fin måte å kategorisere variablene og gir mulighet for nested maps.

Eksempel:

/* abstracts/variables/_breakpoints.scss */

$breakpoints: (
  "mobile": 0,
  "phablet": 36rem /* ~576px */,
  "tablet": 48rem /* ~768px */,
  "tablet-big": 64rem /* ~1024px */,
  "laptop": 80rem /* ~1280px */,
  "desktop": 100rem /* ~1600px */,
) !default;

Ikoner

Alle ikoner skal være i formatet SVG.

Kopier filen

Når vi skal legge til nye ikoner starter det oftest med å gå inn i designsystem-filen i Figma og gå til siden Icons. Velg Copy as SVG på ikonet.

Lag ny SVG-fil

Lag ny fil og lim inn SVG-koden. Navnet på filen skal være id som står i Figma. Legg de først inn i denne folderen:

assets
  └── svg-source/
      └── apple.svg

Klargjør filen

Noen ganger vil man få med ting fra Figma man ikke ønsker i SVG-fila. Derfor må man manuelt sjekke og optimalisere SVG’en med svgo.

Når du står på repoets rot, kjør:

npm run svgo

Det som skjer da er at alle filene som ligger i svg-source blir optimalisert til folderen svg-target. Du må selv flytte filene over til icons-mappen selv. Dette for at man ikke ved et uhell skal skrive over eksisterende filer. Innholdet i disse filene blir ignorert av git.

I optimaliserte SVG-filer, endre alle fill= i path til:

<path fill="var(--fg-color, #2A2859)" ....></path>

Dette gjør det enklere å endre fill-color i css senere.

.error-icon svg {
  --fg-color: red;
}

Legg til data-category slik at ikonene blir kategorisert i dokumentasjonen.

<svg id="apple" data-category="ui" ....>...</svg>

Tilgjengelige kategorier:

  • navigation
  • feedback
  • status
  • ui
  • user
  • social
  • signs
  • activities
  • health
  • food
  • places
  • objects
  • data

Ta kontakt

Vi kan også nåes på Slack hos oslokommune.slack.com på #punkt for en hyggelig prat.