OPH Design System (ODS) on Opetushallituksen verkkopalveluiden käyttöön tarkoitettu muotoilujärjestelmä. Tämä Git-säilö sisältää muotoilujärjestelmän mukaan rakennetun React-komponenttikirjaston.
Huom! Tällä hetkellä komponenttikirjasto on vielä varhaisella kehitysasteella. Käyttöönottoa ei suositella ennen versiota 1.0.0!
- React v18
- Material-UI v6
- Next.js v14 (App router)
- Storybook v8
Versiosta 0.2.0 lähtien komponenttikirjasto on julkaistu Github Packagesiin.
Asentamista varten tarvitaan todennustoken, jonka luontiohjeet löytyvät täältä.
Kun token on luotu, se täytyy ottaa vielä käyttöön npm-paketeille. Lisää kotihakemistoosi .npmrc-tiedostoon seuraavanlainen rivi:
//npm.pkg.github.com/:_authToken=todennustoken
Korvaa "todennustoken" luomasi tokenin merkkijonolla.
Tämän jälkeen täytyy vielä konfiguroida npm käyttämään Github Packagesin pakettivarastoa @opetushallitus-skoopin paketeille. Lisää projektisi .npmrc-tiedostoon rivi:
@opetushallitus:registry=https://npm.pkg.github.com
Asenna komponenttikirjasto samaan tapaan kuin mikä tahansa riippuvuus:
npm i "@opetushallitus/oph-design-system"
Varmista myös, että vertaisriippuvuudet (peer dependency) on asennettu:
{
"peerDependencies": {
"@mui/material": "^6",
"next": "^14 || ^15", // Pakollinen vain, jos käytät Next.js:ää
"react": "^18 || ^19"
}
}Kirjasto sisältää kaksi teema-varianttia: "oph" (sininen) ja "opintopolku" (vihreä). Next.js:ää käytettäessä voit ottaa teeman käyttöön juuritason layoutissa seuraavasti:
import { OphNextJsThemeProvider } from '@opetushallitus/oph-design-system/next/theme';
import { getLocale } from 'next-intl/server';
export async function RootLayout() {
// Voit noutaa käyttäjän kielen millä tavalla haluat, esim. next-intl-kirjastolla
const locale = await getLocale();
return (
<html lang={locale}>
<body>
<OphNextJsThemeProvider variant="oph" lang={locale}>
{children}
</OphNextJsThemeProvider>
</body>
</html>
}Voit noutaa kielen millä tavalla haluat, esimerkiksi next-intl-kirjastolla, kunhan sen arvo on "fi", "sv" tai "en".
Voit myös käyttää teemaa ilman NextJs:ää, pelkällä Reactilla:
import { OphThemeProvider } from '@opetushallitus/oph-design-system/theme';
export function App() {
// Hae käyttäjän kieli esim. selaimen asetuksista, URL:stä tai keksistä
const lang = ['fi', 'sv', 'en'].includes(navigator.language)
? navigator.language
: 'fi';
return (
<OphThemeProvider variant="oph" /* tai "opintopolku" */ lang={lang}>
{/*Tähän teemaa käyttävät komponentit*/}
</OphThemeProvider>
);
}Jos haluat kustomoida teemaa, voit antaa ThemeProviderille Material-UI:n teeman konfiguraatio-objektin osan overrides-parametrina, joka ylikirjoittaa teeman asetuksia.
Teeman initialisointia voi kustomoida luomalla teeman createOphTheme-funktiolla tai useOphTheme-hookilla, joka löytyvät moduulista @opetushallitus/oph-design-system/theme (./src/next/theme/theme.tsx).
Kun teema on otettu käyttöön, voit käyttää ODS:n komponentteja omassa koodissasi:
import { OpenInNew } from '@mui/icons-material';
import { OphButton } from '@opetushallitus/oph-design-system';
export const OmaKomponentti = () => {
return (
<div>
<OphButton startIcon={<OpenInNew />} href="https://opintopolku.fi">
Opintopolku
</OphButton>
</div>
);
};UI-komponenttien dokumentointiin ja testaukseen käytetään Storybook-työkalua.
Main-haarasta muodostettu storybook on nähtävillä osoitteessa: https://dev-files.ops.opintopolku.fi/storybooks/oph-design-system/main/index.html
Jos haluat kehittää ODS:ää tai ajaa Storybookia lokaalisti, sinun täytyy asentaa ensin riippuvuudet:
npm ci
Tämän jälkeen voi käynnistää storybookin lokaalisti kehitys-moodissa:
npm run storybook
Storybook käynnistyy osoitteeseen http://localhost:6006. Muutokset ladataan automaattisesti, kun koodi muuttuu.
Voit myös tehdä tuotanto-buildin komennolla (oletuksena hakemistoon storybook-static):
npm run build-storybook
Moduulin yksikkötestit ovat moduulin kanssa samassa hakemistossa vastaavalla nimellä, mutta tiedostopäätteellä .test.ts(x).
Vitest:llä toteutetut yksikkötestit voi ajaa komennolla:
npm run test
Storybookin visualiset ja saavutettavuustestit on toteutettu Playwright:lla. Jokaiselle storylle tehdään seuraavat tarkistukset:
- Saavutettavuusongelmat @axe-core/playwright-työkalulla.
- Visuaalinen testaus eli kuvakaappausten vertailu, jolla varmistutaan että komponenttien visuaalinen ilme säilyy.
Jotta testit voi suorittaa, täytyy Storybook-palvelimen olla käynnissä osoitteessa http://localhost:6006.
Helpoin tapa ajaa testit on käynnistää Storybookin kehityspalvelin. Tässä on myös se etu, että koodimuutokset ladataan automaattisesti (hot reload).
- Käynnistä storybook-kehityspalvelin:
npm run storybook - Aja testit toisessa terminaalissa joko
- Oman koneen ympäristössä:
npm run test-storybooktai... - Docker-kontissa Ubuntulla:
npm run test-storybook-docker
Testit voi ajaa myös dev-palvelimen sijaan Storybookin tuotantoversiota vasten. Tätä tapaa käytetään CI:ssä, koska testien ajaminen on nopeampaa.
- Muodosta tuotantoversio
--test-optiolla (optio ei pakollinen, mutta nopeuttaa testejä):npm run build-storybook -- --test - Käynnistä muodostettu versio ja aja testit joko
- Oman koneen ympräristössä
npm run start-and-test-storybooktai... - Docker-kontissa Ubuntulla:
npm run start-and-test-storybook-docker
Komponenttikirjaston jakeluversio muodostetaan komennolla:
npm run build
Komento muodostaa EcmaScript-moduulit /dist-hakemistoon käyttäen tsup-työkalua. Package.json-tiedoston export-kentässä on määritelty moduulit, jotka jakeluversio tarjoaa.
Jakeluversion tiedostot on lisätty myös Git-säilöön /dist-hakemistoon, jotta komentoa ei tarvitse ajaa kirjaston asennuksen yhteydessä.
Hakemistosta example löytyy lisäksi Next.js-esimerkkiprojekti, josta voi katsoa mallia komponenttikirjaston käyttöönottoon omassa projektissaan. Esimerkkiprojektilla voi myös testata että komponenttikirjaston jakeluversion käyttöönotto toimii.
Katso lisätietoja Esimerkkiprojektin README:sta.