Storybook
ohjelmisto­kehityksen
työkaluna

Aki Kurvinen

OPINNÄYTETYÖ, Joulukuu 2023

Tietotekniikan tutkinto-ohjelma, Ohjelmistotekniikka

E-kirja:
Julkaistu 10.1.2024, Teksti 30.12.2023

Alkuperäinen teos:
Julkaistu 15.1.2024, Teksti 30.12.2023
https://urn.fi/URN:NBN:fi:amk-202401151415

Arvosana: 4/5

GitHub:
Next.js template v1 (pages router)
Next.js template v2 (app router)

TIIVISTELMÄ

Tampereen ammattikorkeakoulu

Tietotekniikantutkinto-ohjelma, Ohjelmistotekniikka

KURVINEN, AKI: Storybook ohjelmisto­kehityksen työkaluna

Joulukuu 2023

Alma Median asumisen palveluiden käyttöliittymäkehitystä edistettiin määrittämällä hyviä käytäntöjä ja vahvistamalla design systemin roolia. Komponenttiajattelua tuotiin käyttöliittymäsuunnittelijoiden ja ohjelmoijien päivittäiseen työhön ohjeiden ja koulutusten avulla. Kehittäjien käytössä olevan Storybook-työkalun komponenttikirjastoa laajennettiin ja järjesteltiin uudelleen. Samalla yhteiskäyttöisille komponenteille asetettiin tekniset laatuvaatimukset ja visuaalisen testauksen kattavuutta parannettiin aiemmin käyttöön otetulla Chromatic-integraatiolla. Uudistuksessa hyödynnettiin kunkin osapuolen erityisasiantuntemusta ja kuunneltiin toiveita työvaiheiden priorisoinnissa.

Projektin tavoitteena oli edistää käyttöliittymäkomponenttien uudelleenkäytettävyyttä ja ottaa Storybook osaksi päivittäistä ohjelmisto­kehitystyötä kaikissa Alma Median asumisen palveluiden kehitystiimeissä. Uudistuksen pitkänajan merkittävimmäksi hyödyksi arvioitiin kehitystyön nopeutuminen. Tätä tavoitetta edesauttoi käynnissä oleva komponenttien refaktorointi, jossa käyttöliittymäkerros erotetaan muusta ohjelmistologiikasta. Käytännön työssä ohjelmoijaa auttoi Storybookin toiminnallisuus, jolla kehittäjä näkee yhdellä silmäyksellä koodiin tekemiensä muutosten vaikutukset komponentin eri variaatioissa. Kolmantena kehitystyötä ja ylläpidettävyyttä parantava toimintamallina oli Atomic Designiin pohjautuva komponenttien luokittelu. Mallin periaatteena on, että käyttöliittymän suuremmat kokonaisuudet muodostuvat pienemmistä komponenteista. Menetelmän etuna on, että yksittäisiin komponentteihin tehdyt muutokset periytyvät ohjelmistossa monimutk­aisempiin kokonaisuuksiin. Samalla selkeämmin rajattuja kokonaisuuksia on helpompi ymmärtää, kehittää ja testata.

Lopputuloksena syntynyt uudistettu Storybook jäi Alma Median käyttöön ja sitä tullaan päivittämään ja laajentamaan myös jatkossa. Komponenttien uudelleenkäytettävyyttä ja testattavuutta edistäviä toimintamalleja ylläpidetään ja kehitetään samalla.

ABSTRACT

Tampereen ammattikorkeakoulu, Tampere University of Applied Sciences

Degree Programme in ICT Engineering, Software Engineering

KURVINEN, AKI: Storybook as software development tool

December 2023

User interface development was improved in Alma Media housing services production team by defining best practices and reinforcing the role of current design system. Component driven development model was introduced to designers’ and developers’ daily work with guides and trainings. The current Storybook tool’s component library was expanded and rearranged. Withing the process technical quality requirements were set for commonly used components and visual regression testing coverage was improved by defining test cases for the Chromatic integration implemented earlier. Special expertises of each party were utilized and aspirations were considered while prioritizing tasks.

The main goal of the project was to foster reusability of the user interface components and take Storybook as part of user interface development in all Alma Media housing production teams. Acceleration of feature development work was evaluated as the most significant advantage of the reform. This goal was fortified by ongoing component refactoring process where software view layer is separated from other business logic. In practice Storybook helped developers by visualizing user interface components in their different states and variations. Another development and reusability improvement were classification of the components based on Atomic Design. The key advantage in this model was that changes made in smaller components were automatically inherited to larger compositions through the software. At the same time more clearly delimited entities are easier to understand, develop and test.

The new reformed Storybook was left to be used in Alma Media and it will be updated and expanded further on. Operating models fostering the component reusability and testability will be also maintained and evolved.

LYHENTEET JA TERMIT

1 JOHDANTO

Verkkosivujen ja web-sovellusten kasvava dynaamisuus ja interaktiivisuus aiheuttavat haasteita ohjelmisto­kehityksessä, sillä palveluista tulee monimutkaisempia ylläpitää. Perinteinen sivuihin pohjautuva toteutustapa ei riitä kattamaan vaatimuksia vaihtuvalle sisällölle ja yksilöidyille palveluille. Komponenttien keskinäiset riippuvuudet ja tiedonsiirron asynkronisuus muuttavat myös osaltaan perinteistä mallia yhdellä kertaa renderöitävästä sivusta. Tässä opinnäytetyössä keskitytään käyttöliittymäkehitykseen ja siihen liittyviin dynaamisuuden tuomiin mahdollisuuksiin ja haasteisiin.

Palveluiden dynaamisuus näkyy käyttöliittymäkomponenteissa vaatimuksena erilaisiin tilanteisiin mukautuvina variaatioina. Palveluiden kansainvälistyminen, internetin laajamittainen käyttö mobiililaitteilla sekä digitaalisten palveluiden saavutettavuusvaatimukset lisäävät tarvittavien variaatioiden määrää entisestään.

Käyttöliittymäkomponenttien hallintaan on luotu useita kehitystyökaluja, joilla niiden eri variaatioita voidaan listata, dokumentoida ja testata. Tässä opinnäytetyössä esitellään laajasti tunnettu Storybook, jolle on saatavilla useita lisäosia ja integraatioita.

Komponenttiajattelu on oleellinen osa design-, sekä ohjelmointityötä skaalautuvien palveluiden parissa. Komponenttiajattelua havainnollistetaan käyttöliittymien kehitykseen keskittyvällä Atomic Design -mallilla, jonka on kehittänyt design system -konsultti Brad Frost. Mallin tarkoitus on auttaa suunnittelijoita ja ohjel-mistokehittäjiä purkamaan käyttöliittymä pienempiin osiin ja erottamaan se muusta ohjelmistologiikasta. Siten komponenteista saadaan helpommin ylläpidettäviä ja uudelleen­käytettäviä. Atomic Design -mallia on sittemmin laajennettu muilla tyylielementeillä kuvaamaan paremmin nykyaikaisen design systemin ominaisuuksia.

Opinnäytetyönä toteutettu Storybook-uudistus tehtiin työsuhteessa Alma Medialla, joka oli samalla työn tilaaja. Projektiin sisältyi myös visuaalisen testauksen kattavuuden parantamista sekä käyttöliittymäkehityksen hyvien työtapojen kartoittamista ja kehittämistä.

2 STORYBOOK

Storybook on avoimen lähdekoodin kehitystyökalu, joka auttaa ohjelmisto­kehit-täjiä luomaan ja ylläpitämään käyttöliittymäkomponentteja. Samalla se toimii myös dokumentointityökaluna, johon listataan käyttöliittymäkomponenttien eri variaatiot, käyttökohteet ja tarvittaessa muut projektin kannalta oleelliset tiedot. Storybookin kanssa voi soveltaa MVVM (model-view-viewmodel) -ohjelmisto­arkkitehtuuria, jossa keskeinen periaate on erottaa käyttöliittymäelementit muusta koodista eli niin kutsutusta bisneslogiikasta. Tällöin käyttöliittymäkomponenteista saadaan laajemmin uudelleen­käytettäviä ja helpommin ylläpidettäviä. (Storybook n.d.a)

”Niin kauan kuin Storybook nähdään vain dokumentointityökaluna, se ei tule saavuttamaan organisaatiossa minkäänlaista käytännöllistä asemaa. Storybook tulee nähdä ensisijaisesti ohjelmoijan kehitys- ja laadunvarmistustyökaluna.” -Lauri Nevanperä, Front End Software Architect, Alma Media

Storybook auttaa kehittäjää palvelun teemaan ja UI (user interface) -kirjastoon tehtävissä muutoksissa. Jokaisen komponentin löytäminen sen kussakin mahdollisessa tilassa on suuressa ohjelmisto­projektissa manuaalisesti lähes mahdoton tehtävä, joten komponenttienvariaatioiden tarkka listaus Storybookissa ratkaisee ongelman. Visuaalista testausta voidaan osittain myös automatisoida Chromatic-integraatioilla. (SemiDesign 2022)

2.1 Komponenttien lisääminen Storybookiin

Storybook toimii parhaiten, kun sinne lisätään ainoastaan näkymäkomponentteja (view component), joiden tarkoitus on tiedon näyttäminen varsinaisen logiikan ja laskennan tapahtuessa muualla. Koska näkymäkomponentti saa kaiken datan parametreina, sen toimintaa voidaan demonstroida Storybookissa antamalla komponentille keksittyjä arvoja. API (application programming interface) -logiikkaa sisältävien komponenttien lisääminen Storybookiin on teknisesti mahdollista, mutta toistuvien palvelinkutsujen sijaan on hyvä käyttää keksittyä mock-dataa.

Komponenteista voi olla perustilan lisäksi muita tyylillisiä tai toiminnallisia variaatioita. Toiminnalliset tilat, kuten lataustila, ei muokattavissa, ei näytettävää dataa ja virhetila viestivät käyttäjälle ohjelmiston tapahtumista. Tyylilliset variaatiot, kuten napin täytetty ja ääriviivallinen versio liittyvät sen sijaan sivuston hierarkiaan, joka auttaa käyttäjää navigoimaan palvelussa.

Jokainen variaatio muodostaa yhden tarinan (story), jotka havainnollistetaan Storybookissa syöttämällä komponentille tilanteen aiheuttavat argumentit. Tarinalle annetaan myös tilanneetta kuvaava nimi. Napilla voi olla tarinat Contained ja Outlined, jotka tarkoittavat napin täytettyä ja ääriviivallista veriosta (kuva 1).

Mock-dataa käyttämällä käyttöliittymäkomponenttien kehitystyö voidaan aloittaa jo varhaisessa vaiheessa designin pohjalta ennen kuin varsinaista API:a on ehditty toteuttamaan. Erottamalla käyttöliittymä bisneslogiikasta, palvelinkutsujen ja tilan hallinnan kehitystyö voi tapahtua eri tiedostoissa, mikä ehkäisee ristiriitoja Gitin kehityshaaroja yhdistäessä.

2.2 Storybookin lisäosat

Storybookiin voidaan asentaa lisäosia projektin tarpeiden mukaan. Valikoima on erittäin laaja ja virallisten lisäosien lisäksi löytyy myös paljon yhteisön tuottamia lisäosia. Storybookin vahvuus onkin sen laajennoksissa ja integraatioissa.

Essential-lisäosat tulevat mukana Storybookin asennuspaketissa ja ovat pääohjelmisto­kehitystiimin ylläpitämiä. Storybookin perusasennukseen kuuluu mm. työkalut komponentin näyttämiseen erikokoisilla näytöillä, sekä interaktioiden simulointiin (Storybook n.d.b). Erikseen asennettavat Core-lisäosat ovat myös päätiimin hallinnoimia ja niitä päivitetään Storybookin mukana. Community-lisäosat ovat nimensä mukaan yhteisön ylläpitämiä, eikä Storybook vastaa niiden yhteensopivuudesta uusien Storybook-versioiden kanssa. (Storybook n.d.c). Lisäosan tyypistä riippuen, sillä voi olla kuvake työkaluvalikossa (mm. teemalisäosa) tai laajempi näkymä Storybookin alapalkissa, kuten Figmassa luotujen designien upottamiseen tarkoitetulla addon-designs:lla (kuva 2).

2.3 Saavutettavuus

Saavutettavuus tarkoittaa, että verkkosivut, sovellukset ja muut digitaaliset pal-velut ovat kaikkien ihmisten käytössä fyysisitä tai kognitiivisista toimintarajoit-teista huolimatta. Samalla pyritään varmistamaan tasavertainen tiedonsaanti sekä mahdollisuus osallistua ja vaikuttaa. (Invalidiliitto n.d.)

Komponenttien saavutettavuutta voidaan testata Storybookin Accessibility-lisäosalla (kuva 3). Lisäosa tarkistaa komponentit mm. puuttuvien aria- ja title-kenttien tai tyhjien ja siten ruudunlukijalle näkymättömien elementtien varalta. Värikontrastin tarkistuksella taataan, että teksti erottuu selvästi taustaväristä ja on helposti luettavissa. Luettavuuteen vaikuttaa myös fontti ja tekstin koko, jota käyttäjän on hyvä päästä halutessaan säätämään. Riittävä kontrasti auttaa mm. heikkonäköisiä tai kirkkaassa auringonpaisteessa puhelintaan selaavia käyttäjiä navigoimaan sovelluksessa helpommin. Saavutettavuuden yhteydessä puhutaankin usein pysyvästä, tilapäisestä tai tilanteen aiheuttamasta toimintakyvyn heikkenemisestä. (Google n.d.; Storybook n.d.d)

3 UI-KOMPONENTTIEN TESTAUS

Ohjelmistotuotannossa käyttöliittymäkomponentteja testataan sekä toiminnallisesti, että visuaalisesti. Suurin osa testauksesta suoritetaan testiautomaatiolla, jossa ihmistä tarvitaan lähinnä kirjoittamaan testitapauksia ja analysoimaan tuloksia. Lisäksi koodin toimintalogiikkaa ja käyttöliittymän visuaalisia elementtejä katselmoidaan manuaalisesti tuotantotiimin kesken. Ohjelmoijan ja koodikatselmoijan kannalta ohjelmistoarkkitehtuurimalli, jossa käyttöliittymäkomponentit luodaan erillään muusta logiikasta, auttaa pitämään testauksen vaiheet rajattuina ja helpommin ymmärrettävinä. (Nevanperä, L. 2022)

3.1 Testauksen vaiheet

Näkymäkomponenttia testattaessa osapuolien tarvitsee keskittyä ainoastaan komponentin ulkoasuun ja siihen, että argumentteina annettu data näkyy oikein. Tähän sopivia työkaluja ovat erinäiset visuaalisen regressiotestauksen työkalut, kuten Chromatic, jota esitellään tarkemmin jäljempänä.

Käyttöönottovaiheessa puolestaan toteutetaan tiedonsiirtoon keskittyvä ohjainkomponentti, joka käyttää näkymäkomponentteja tiedon näyttämiseen. Optimaalisessa tilanteessa kehittäjien ei siten tarvitse enää huolehtia näkymäkomponenttien sisäisestä toimivuudesta, vaan testauksessa voidaan keskittyä täysin ohjainkomponentin bisneslogiikan testaukseen.

Viimeisessä end-to-end testausvaiheessa ohjainkomponentti lisätään sivulle sille varattuun paikkaan. Testattavaksi jää layoutin (elementtien asettelun) eheys ja palvelun toimivuus kokonaisuutena.

3.2 Visuaalinen regressiotestaus

Komponenttien visuaalinen regressiotestaus täydentää testiautomaatiota, joka usein keskittyy ainoastaan ohjelmiston tekniseen toimivuuteen eikä niinkään sen graafiseen ulkoasuun. Käyttäjän kannalta on kuitenkin oleellista, että käyttöliittymäelementit ovat oikeassa paikassa, löytyvät helposti ja näyttävät kuuluvan kokonaisuuteen. Palvelun ulkoasu, brändiin sisältyvät graafiset elementit ja käyttäjä­kokemuksen yhdenmukaisuus vaikuttavat käyttäjän mielikuvaan palvelun laadusta ja luotettavuudesta.

3.3 Chromatic-testaustyökalu

Chromatic on käyttöliittymäkomponenttien visuaaliseen testaukseen tarkoitettu työkalu. Sen avulla käyttöliittymäelementeissä tapahtuneita tahattomia tai tarkoituksellisia graafisia muutoksia voidaan havaita ja vertailla kehitystyön edetessä. (Chromatic n.d.a)

Chromatic kytketään usein osaksi GitHub repositoryn pull requestin (yhdistäminen pääkehityshaaraan) yhteydessä tapahtuvaa testiautomatiikkaa, mutta sen voi suorittaa myös erikseen komentoriviltä. Chromaticin toiminnan edellytyksenä on, että projekti käyttää Storybookia. Chromatic-testin aikana työkalu luo kaikista komponenteista snap shotit eli niin sanotut kuvakaappaukset. Muutosten tunnistaminen nykyisen ja edellisen kuvakaappausversion välillä tapahtuu automatisoidusti (kuva 4).

Katselmoinnista vastaava henkilö voi tarkastella ja kommentoida Chromaticin havaitsemia muutoksia komponenttien ulkoasussa ja samalla hyväksyä tai hylätä ne (kuva 5). Tyypillisiä vaikeasti havaittavia käyttöliittymäelementtien muutoksia ovat pienet mittasuhteiden ja marginaalien muutokset sekä värisävyjen hienoinen vaihtuminen. Chromaticin automatiikka havaitsee kuitenkin tämän kaltaiset muutokset tehokkaasti ja havainnollistaa ne korostusvärillä katselmointia suorittavalle henkilölle (kuva 6).

Storybook on mahdollista julkaista Chromaticin kautta ja asettaa nähtäville joko vain kehitystiimille tai myös kaikille kirjautumattomille käyttäjille. Chromaticin kautta julkaiseminen tarjoaa mahdollisuuden tarkastella Storybookin sisältämien komponenttien aikaisempia versioita sekä jakaa ja upottaa niiden esikatseluita muihin sovelluksiin (kuva 7).

3.4 Teema-, päätelaite- ja kieliversiot

Beta-vaiheessa oleva TurboSnap pyrkii vastaamaan kasvavaan snap shottien määrään renderöimällä ainoastaan muuttuneet komponentit. Se tunnistaa komponenttien riippuvuudet Gitin ja Webpackin avulla. TurboSnapin asetuksia voi muuttaa GitHub Actions:ssa ja komentoriviparametreilla. Toisinaan lieveilmiönä esiin tulevat, todellisista komponenteista poikkeavat snap shotit saattavat aiheuttaa ongelmaa, joten välillä on hyvä tarkistaa, milloin komponentin kuvakaappaus on viimeksi päivitetty. (Chan, M. 2023; Chromatic n.d.b)

4 DESIGN SYSTEM

Design system on työkalu digitaalisten palveluiden tehokkaampaan ja johdonmukaisempaan kehitykseen. Se voi sisältää projektista ja tiimistä riippuen hyvin erilaisia osioita, joista tyypillisimpiä ovat komponenttikirjasto, visuaaliset tyylit sekä ohjeet ja dokumentaatio. Design systemin käyttöön­otolla voidaan parantaa front end -painotteisen ohjelmisto­kehityksen tehokkuutta ja käyttäjä-kokemuksen yhdenmukaisuutta. (Atlassian n.d.; Wunder n.d.)

4.1 Design tokens

Design tokeneilla kuvataan visuaalisten elementtien, kuten käyttöliittymäelementtien graafisia ominaisuuksia. Tyypillisimpiä design tokeneita ovat värit ja fontit. Määrittelemällä kukin fontti ja värisävy design tokeniksi, saadaan käsitys siitä, kuinka monta erilaista fonttia ja väriä palvelun toteutukseen tarvitaan (kuva 12). Määrä saattaa yllättää, jos tokenit luodaan jälkikäteen olemassa olevan palvelun pohjalta. Tässä vaiheessa onkin hyvä tilaisuus käydä läpi ne kaikki palvelusta löytyneet kymmenen pääväriä ja viisikymmentä harmaansävyä ja alkaa samalla yhtenäistämään niiden käyttöä. Fonttien ja kirjainkokojen määrää on myös hyvä rajoittaa, mikäli mahdollista. (Frost, B. 2019)

Erikseen määritetyistä tokeneista, kuten väriarvoista ja fonteista on erityistä hyötyä saavutettavuus­testauksen kannalta, sillä erilaisten fonttikokojen ja väriyhdistelmien luettavuus voidaan tarkistaa jo ennalta. Jos testeissä havaitaan ongelmia, voidaan korjaukset tehdä keskitetysti koko palveluun.

Kokoon liittyvillä tokeneilla, kuten marginaalit, paddingit, reunaviivanpaksuudet ja mediaqueryt, voidaan yhtenäistää sivun asettelua ja hyödyntää grid systemiä. Mediaqueryillä ja grid systemillä hallitaan käyttöliittymäelementtien mukautumista eri pääteleitteiden ruutujen kokoihin sopiviksi. Nettisivulla näkyvien laatikoiden koot ja niiden väliin jäävä tyhjä tila eivät siis ole sattumanvaraisia, vaan ne on määritelty jo design systemissä. (LähiTapiola 2023)

Muita eksoottisempia tokeneita voivat olla animaatiot, siirtymäefektit, heittovarjot, kulmanpyöristykset ja syvyystasot (z-index). Kaikkien edellä mainittujen arvojen tarkoitus on yhtenäistää palvelun graafista ilmettä, toiminnallisuutta ja käyttäjä­kokemusta.

4.2 Komponenttikirjasto

Komponenttikirjasto kokoaa kaikki koodissa käytetyt käyttöliittymäelementit yhteen paikkaan. Komponenttien tehokas ylläpidettävyys saavutetaan paketinhallintajärjestelmää hyödyntämällä. Optimaalisessa tilanteessa tismalleen sama UI-komponentti on käytössä tuotannossa sekä dokumentaatiossa. Tämä toimintatapa vähentää päivittämiseen tarvittavaa työmäärää ja toteuttaa samalla yhden totuudenlähteen periaatteen (SSOT), missä komponentista ei ole olemassa rinnakkaisia versioita. Pieniä eroavaisuuksia voi kuitenkin ilmetä designin ja tuotannon välillä, sillä suunnittelijan käyttämät komponentit ovat interaktiivisuudestaan huolimatta lähinnä graafisia esityksiä ohjelmisto­kehittäjän kirjastossa olevista vastineista (kuva 13). (Material UI n.d.)

4.3 Skaalautuvuus

Siinä missä perinteinen pdf-tiedostona toimitettava graafinen ohjeisto on suppea ja staattinen, nykyaikainen design system on laaja ja dynaaminen. Laajuus kannattaa toki suhteuttaa projektin kokoon ja pituuteen, sillä design systemin hyödyt korostuvat usein vasta pidemmällä aikavälillä jatkuvassa ohjelmisto­kehityksessä. Hyvä design system skaalautuu projektin kasvaessa samalla säilyttäen tehokkaan ylläpidettävyyden. Skaalautuvuus tässä asiayhteydessä tarkoittaa sitä, että kehitystiimin on helppo käyttää olemassa olevia komponentteja uusien ohjelmiston ominaisuuksien ja laajempien kokonaisuuksien toteutukseen. (Orozco, E. 2022)

4.4 Työskentelytavat

Design systemissä voidaan määrittää tiimin työskentelyyn ja kommunikointiin liittyviä hyviä käytänteitä. ohjelmisto­kehittäjän kannalta merkittäviä ohjeistuksia ovat design systemin soveltamisohjeet, käyttöönotto sekä koodikatselmointiin ja uusien ominaisuuksien toteuttamiseen liittyvät menettelytavat. Joissain design systemeissä on hahmoteltu jopa polku uusien komponenttien lisäämiselle ja vanhojen refaktoroinnille. (Somers, M. 2015)

Kommunikaatioon suunnittelijoiden ja kehittäjien välillä voidaan määrittää suuntaviivoja, joiden tarkoitus on auttaa osapuolia ymmärtämään toisiaan. Ohjeisiin voi sisältyä kohtia, kuten: Mitä asioita designer voi huomioida jo suunnitteluvaiheessa auttaakseen kehittäjää toteuttamaan komponentin tai ominaisuuden? Entä miten designiin pystytään ehdottamaan muutoksia, jos toteutuksessa kohdataan ylitsepääsemättömiä teknisiä rajoitteita? Yhteinen kieli ja yhteiset työkalut edesauttavat kommunikointia, mutta psykologisesti turvallisen ympäristön tuomaa lisäarvoa ei voi sivuuttaa. (Cubilla, J. 2022)

4.5 Design

Nykyaikainen web-design ei ole pelkästään staattinen kuva sivustosta tai komponentista, vaan interaktiivinen esitys palvelun toiminnasta. Laajemmin ajateltuna design on ratkaisu käyttäjän ongelmaan. Suunnitteluohjelmat ovat viime vuosien päivitysten myötä kaventaneet designin ja ohjelmoinnin eroavaisuuksia entisestään. Mukautuvat layoutit, ehtolausekkeet ja muuttujat sekä monimutkaiset komponenttirakenteet variaatioineen tarjoavat designerille laajat työkalut suunniteluun. Samalla kehittäjä saa hyödyllistä informaatiota palvelun toiminnasta, elementtien variaatioista sekä asemoinnista layoutissa. (Figma 2023)

Näiden ominaisuuksien ansiosta palvelun toimintaa voidaan havainnollistaa tilaajalle todentuntuisella interaktiivisella prototyypillä jo ennen kehitystyön aloittamista. Tämä mahdollistaa käyttäjä­kokemukseen liittyvien ongelmien korjaamisen mahdollisimman aikaisin ja resursseja säästäen.

5 ATOMIC DESIGN

Todellisten ohjelmistoprojektien käyttöliittymärakenteet ovat hyvin monimutkaisia ja komponentteja on paljon. Etenkin uuden kehittäjän saattaa olla vaikea päästä perille kansiorakenteista ja löytää oikeat osat kunkin toiminnon toteuttamiseen.

Eräs malli komponenttien luokitteluun on Brad Frostin kehittämä Atomic Design -suunnittelu­järjestelmä. Se perustuu käyttöliittymäkomponenttien jakoon viidelle tasolle niiden kompleksisuuden mukaan. Keskeinen periaate on, että monimutkaisemmat kokonaisuudet koostuvat alemman tason yksinkertaisemmista komponenteista, jolloin niihin tehdyt muutokset periytyvät ohjelmistossa ylöspäin. Uudelleenkäytettävyyden ja ylläpidettävyyden lisäksi kyseinen luokittelu auttaa hahmottamaan hierarkiaa. (Frost, B. 2016a)

5.1 Atomit (atoms)

Atomi on järjestelmän pienin yksikkö, jota ei voida tai projektin kannalta hyödytä jakaa pienempiin osiin. Atomi voi olla yksittäinen nappi, teksti, kuva, syötekenttä tai muu HTML-peruselementti. Jotta atomi on helposti uudelleenkäytettävissä eri palvelun osissa ja asiayhteyksissä, se ei voi sisältää kovakoodattuja väriarvoja, tekstejä tai bisneslogiikkaa. (Frost, B. 2016b)

Siinä missä design token on abstrakti visuaalista tyyliä kuvaava arvo, atomi on konkreettinen komponentti, jolla on toiminto. Atomilla on usein eri variaatioita, jotka hyödyntävät design tokeneita (kuva 14).

5.2 Molekyylit (molecules)

Molekyyli on muutamasta atomista koostuva verrattain yksinkertainen käyttöliittymän osa. Molekyylit antavat atomeille asiayhteyden muodostaen niistä kokonaisuutena uuden toiminnallisuuden (kuva 15). Esimerkiksi syötekenttä, suurennuslasi-ikoni ja nappi muodostavat yhdessä käyttöliittymän hakutoiminnolle.

Molekyyli ei kuitenkaan itsessään sisällä haun toteuttavaa API-kutsua tai tilahallintaa. Sitä vastoin bisneslogiikka tulee toteuttaa ohjelmistossa ylemmällä tasolla ja välittää interaktiot sekä muutokset komponentille argumentteina.

Pitämällä molekyylit riittävän yksinkertaisina, niiden toiminnallisuutta pystytään rajaamaan tehokkaasti, jolloin uudelleenkäytettävyys ja testattavauus paranevat. Hakukenttämolekyyli on vastuussa ainoastaan käyttäjän syötteen vastaanottamisesta ja haun käynnistävän signaalin välittämisestä nappia painettaessa.

5.3 Organismit (organisms)

Organismi on monimutkaisempi kokonaisuus, joka koostuu molekyyleistä ja voi lisäksi sisältää yksittäisiä atomeita (kuva 16). Se muodostaa palveluun toiminnon, jolle on osoitettu layoutissa oma lohkonsa.

Sivuston header-palkki (organismi) koostuu usein päänavigaatiosta ja hakukentästä, jotka ovat molekyylejä. Lisäksi headerissa voi olla yrityksen logo, joka on kokonaisuutta täydentävä yksittäinen atomi.

Bisneslogiikkaa sisältävä organismi voi toimia täysin itsenäisenä widgettinä riippumatta sivun muista lohkoista. Uudelleenkäytettävyyden takaamiseksi, kannattaa kuitenkin harkita logiikan siirtämistä sivutasolle tai erilliseen kontrolleriin. Suositeltavaa on, etteivät organismeja pienemmät komponentit sisällä myöskään bisneslogiikkaa. (Fox, B. 2021)

5.4 Sivupohjat (templates)

Template, eli sivupohja toimii runkona keskenään samantyyppisille sivuille. Tyypillisiä sivupohjia ovat etusivu, listasivu ja tuote- tai artikkelisivu. Koodissa templaten tarkoitus on muodostaa sivulle rakenne määrittämällä lohkojen koot ja paikat responsiivisuus huomioiden (kuva 17). Templatet eivät sisällä bisneslogiikkaa. Designissa template vastaa tarkkuudeltaan lähinnä rautalankamallia. Figman komponentteihin liittyvien rajoitteiden takia, templatea ei pystytä vielä hyödyn-tämään designissa samaan tapaan kuin koodissa. (Munawar, M. 2023)

5.5 Sivut (pages)

Sivu on templateen pohjautuva uniikki näkymä, joka näyttää todellisen sisällön (kuva 18). Samalla se on Atomic Design -systeemin ylin ja konkreettisin taso. Esimerkiksi kukin uutissivuston artikkeli on uniikki, mutta kaikki artikkelisivut käyttävät pohjana samaa mallia. Sivuilla voi olla tilanneriippuvaisia ominaisuuksia kuten maksumuurit, ylläpitäjän työkalut tai vierailevalle käyttäjälle personoidut ilmoitukset.

Teknisen toteutuksen kannalta sivu on vanhakantainen määritelmä, joka kantautuu ohjelmisto­kehitykseen printtimedian aikakaudelta. Uutissivuston artikkelit eivät ole palvelimella erillisiä artikkelitiedostoja vaan sama artikkelisivupohja pystyy näyttämään minkä tahansa artikkelin sisällön. Se pystyy samalla tarkistamaan, onko käyttäjä kirjautunut tai maksanut lehden kuukausitilauksen. Täsmällisempää olisikin puhua sivujen sijaan visualisointimalleista. Kullekin erilaiselle datatyypille on front endissä malli, jolla kyseinen tieto esitetään käyttäjälle graafisesti. Tämä mahdollistaa sen, että tuhansien sivujen sijaan monimutkainenkin web-palvelu saattaa sisältää vain muutaman sivupohjan, joilla kaikki tieto saadaan esitettyä. (Frost, B. 2016a)

6 KÄYTTÖLIITTYMÄ­KOMPONENTIT

Atomic Designin atomit ja molekyylit toimivat MVVM-ohjelmistoarkkitehtuurin näkymätasolla (view), koska muu bisneslogiikka ja tilan hallinta on erotettu käyttöliitymäkomponenteista.

Kun UI-komponentti otetaan käyttöön, se kääritään osaksi ohjainkomponenttia (controller), joka on Atomic Designissa organismi tai sivu. Ohjainkomponentti suorittaa varsinaisen tiedonsiirron, laskennan ja tilanhallinnan. Ohjain hyödyntää näkymäkomponenttia antamalla sille argumentteina datan, joka halutaan näyttää käyttäjälle (kuvio 1). Se voi renderöidä tarvittaessa useita eri näkymäkomponentteja ja vastaanottaa käyttäjän tekemiä interaktioita, kuten napin painallukset.

Sivut koostuvat lähes poikkeuksetta useista itsenäisesti toimivista organismeista, kuten navigaatiot, artikkelit ja galleriat. Sivu voi hyödyntää Atomic Designin templatea lohkojen asemointiin, mutta bisneslogiikka on pidettävä erillään sivupohjasta.

6.1 Komponenttien uudelleenkäytettävyys

Tyypillinen esimerkki front endin kerroksellisuudesta on tuotekatalogin haku tietokannasta ja näyttäminen käyttäjälle. Ohjaimena toimiva listasivu (page) tekee tuotetietokyselyn palvelimelle ja saa back endiltä vastauksena tuotteiden saatavuustiedot. Sivu renderöi tiedot näkyville syöttämällä ne parametreina näkymäkomponentille. Tässä tapauksessa näkymäkomponentti voi olla logiikaton taulukko-organismi, joka puolestaan käyttää yksittäisiä rivimolekyylejä tiedon näyttämiseen. Pelkästään API-kutsua muuttamalla taulukossa voidaan näyttää minkä tahansa varaston tiedot.

6.2 Logiikaton organismi

Jättämällä API-logiikka pois organismin sisältä, komponentti voidaan toteuttaa täysin geneerisenä ja uudelleenkäytettävänä muissa asiayhteyksissä. Riippuen taulukkokomponentin toteutuksesta, ohjaimen (sivun tai muun organismin) toimintaa muuttamalla siinä voitaisiin periaatteessa näyttää myös viikon ruokalista tai jonkun pörssiosakkeen kurssivaihtelut.

UI-komponenttien geneerisyysvaatimus on kuitenkin hyvin projektikohtaista. Maksimoimalla uudelleenkäytettävyys, saadaan kertaalleen toteutettuja komponentteja hyödynnettyä projektin muissa osissa ja siten nopeutettua palvelun ominaisuuksien kehitystä. Liika geneerisyys ja lukemattomissa paikoissa uudelleen käytetyt monimutkaiset komponentit kuitenkin vaikeuttavat muutosten tekemistä, sillä huomioitavien asioiden määrä kasvaa. Atomit ja molekyylit ovat hyvin yksinkertaisia ja sen takia niistä on helppo saada laajasti uudelleen­käytettäviä.

6.3 Itsenäinen organismi

Atomic Desining periaatteiden mukaisesti organismi voi myös itsessään sisältää bisneslogiikan ja palvelinkutsut. Tämä mahdollistaa komponentin itsenäisen toiminnan. Palvelun footerissa voi olla esimerkiksi säätietowidgetti, joka hakee säätiedot palvelimelta ja näyttää ne käyttäjälle. Widgetin toiminta ei ole kriittinen muun sivun kannalta, joten säätietohaun onnistumista tai epäonnistumista ei tarvitse monitoroida ylemmällä tasolla. Logiikan sisällyttäminen komponenttiin rajoittaa kuitenkin sen uudelleenkäytettävyyttä.

7 REFAKTOROINTI

Refaktorointi tarkoittaa prosessia, jonka tarkoitus on selkiyttää ja tehostaa olemassa olevaa koodia muuttamatta sen toiminnallisuutta. Refaktoroinnissa voidaan muokata koodin rakennetta tai päivittää siinä käytettyjä kirjastoja.

Käytetään refaktorointiesimerkkinä tuotekatalogikomponentti-organismia (koodissa StockPanel), joka näyttää käyttäjälle varaston kaikki tuotteet, niiden lukumäärän sekä esikatselukuvan (kuva 19). Uudelleenkäytettävyyden ja testattavuuden parantamiseksi bisneslogiikka halutaan eriyttää tuotekatalogior-ganismista. Lisäksi erillisistä CSS-moduuleista halutaan eroon ja listan osista halutaan helpommin hallittavia kokonaisuuksia.

7.1 Alkutilanne

Oletetaan, että alkuperäinen tuotekatalogikomponentti on toteutettu niin kutsuttuna itsenäisenä organismina, joten se sisältää kaiken tarvitsemansa tiedonsiirto- ja tilanhallintalogiikan (Liite 1).

Tilanhallintaan liittyviä toimintoja ovat esimerkissä käytetty React-kirjaston useState ja useEffect. Näillä hookeilla hallitaan palvelimelta fetch-kirjastolla haettua dataa sekä esikatselussa käyttäjälle näkyvää kuvaa. Käyttäjän toimintoja vastaanotetaan onClick-tapahtumakäsittelijällä, joka vaihtaa listalta valitun tuotteen komponentin tilaan (state) ja siten esikatseluun.

Tuotelistan renderöinti on kokonaisuudessaan sisällytetty organismiin, eikä se hyödynnä osanaan pienempiä kokonaisuuksia kuten molekyylejä tai atomeita. Poikkeuksena tähän ovat Typography ja IconButton atomit, joka käyttävät MUI-teemassa määriteltyjä värejä ja fontteja. Muut organismin tyylit on määritelty erilliseen CSS-tiedostoon (Liite 2), josta ne on tuotu luokkina kullekin elementille className-attribuuttina.

7.2 Lopputilanne

Tuotekatalogin refaktoroinnissa komponentti jaettiin useaan tiedostoon, joista päätason organismeja ovat näkymä- ja ohjainkomponentti (koodissa StockPanelView ja StockPanelController).

Tiedonsiirto ja tilan hallinta on siirretty ohjainkomponenttiin (Liite 3), joka datan saatuaan välittää sen eteenpäin näkymäkomponentille (Liite 4). Latausvaiheessa ohjain näyttää erillistä skeleton-komponenttia (kuva 20), jonka tarkoitus on varata käyttöliittymästä etukäteen tilaa taulukolle ja siten vähentää sivun elementtien siirtymistä ruudulla latauksen valmistuttua (kuva 21).

Näkymäkomponentti ei sisällä tilan hallintaa tai API-kutsuja, vaan saa näyttämänsä datan argumentteina. Käyttäjän klikkauksista suoritettavat funktiot on myös välitetty näkymänkomponentille samalla periaatteella. Erillisessä tyylitiedostossa olleet CSS-tyylit on sisällytetty komponentteihin käyttämällä Emotion-kirjastoa ja styled-komponentteja. Onnistuneen refaktoroinnin jälkeen komponentti vastaa ulkonäöltään täysin alkuperäistä ja sen sisältämiä tiloja voidaan demonstroida Storybookissa (kuva 22).

Tuotteen esikatselu on toteutettu erillisenä komponenttina (koodissa Figure), joka saa parametreina näytettävän kuvan polun ja tuotteen nimen (kuva 23). Figure on kustomoitu versio HTML:n perustagista figure, johon img-tagin tilalle on vaihdettu Next.js-frameworkin Image-kuvakomponentti (Liite 5).

Refaktoroidussa versiossa tuotelista on eriytetty omaksi organismitason komponentikseen (koodissa StockList), joka renderöi parametrina välitetyn datan taulukkomuotoon (Liite 6). Listaorganismi muodostuu useasta rivimolekyylistä (kuva 24).

Datarivejä käsitellään map-funktiolla, jossa kustakin havainnosta eritellään tuotteen nimi ja lukumäärä argumenteiksi rivikomponentille (liite 7). Rivikomponentti (koodissa StockItem) luokitellaan Atomic Designissa molekyyliksi, koska se käyttää atomeita datan näyttämiseen. Rivimolekyylistä on toteutettu useita variaatioita eri tilanteisiin (kuva 25). Komponentti palauttaa li (list item) HTML-peruselementin. Listaelementti sisältää Typography-komponentin sekä IconButton klikattavan kuvakkeen (kuvat 26 ja 27), jotka käyttävät MUI-teeman väri- ja tekstityylejä (kuvat 28 ja 29).

8 PROJEKTI

Alma Median asumisen palveluiden ohjelmisto­kehittäjien ja designereiden käytössä olevan Storybookin rakennetta päivitettiin osana opinnäytetyötä. Samalla parannettiin visuaalista testiautomaatiota ja kehitettiin työmenetelmiä.

8.1 Tavoitteet

Storybook driven development -ohjelmisto­kehitysmallin on tarkoitus nopeuttaa palveluiden front end -kehitystä pitkällä aikavälillä parantamalla komponenttien uudelleenkäytettävyyttä ja testattavuutta. Samalla luotiin toimintamalleja, jotka auttavat ylläpitämään ja laajentamaan komponenttikirjastoja sekä parantamaan kommunikaatiota designereiden ja kehittäjien välillä.

8.2 Työmenetelmät

Projektia varten perustettiin joka toinen viikko kokoontuva työryhmä, johon osallistui useita designereita ja ohjelmisto­kehittäjiä. Palavereissa kartoitettiin tiimien tarpeita, priorisoitiin toteutettavia ominaisuuksia ja esiteltiin teknologioita sekä projektin edistymistä. Opinnäytetyön tekijä valmisteli palaverien agendan ja vei projektia eteenpäin sovittujen vaiheiden mukaisesti. Aiheina palavereissa oli mm. Storybookin kansiorakenne, vaatimusmäärittely yhteis­käyttöisille komponenteille, visuaalisen testauksen edistäminen sekä ohjelmointi- ja designtiimien työmenetelmien kehittäminen. Kokonaisuuteen sisältyi myös koulutuksia työkaluista ja design systemistä.

8.3 Lopputulos

Storybookin rakenne järjestettiin uudelleen vastaamaan paremmin eri palveluiden parissa työskentelevien tiimien tarpeita. Palvelukohtaisten komponenttien järjestystä yhdenmukaistettiin ja yhteiskäyttöisille komponenteille asetettiin selkeät laatuvaatimukset. Visuaalista testausta laajennettiin Chromaticissa siten, että komponentit pystytään tarvittaessa visuaalisesti testaamaan palvelukohtaisten teemojen lisäksi eri kieliversioilla sekä erikokoisilla päätelaitteilla. Samalla luotiin käyttöliittymäkehityksen työskentelytapoja, jotka ylläpitävät ja tukevat projektissa asetettuja tavoitteita myös tulevaisuudessa.

9 JOHTOPÄÄTÖKSET JA POHDINTA

Kattavan design systemin hyödyt korostuvat jatkuvassa ohjelmisto­kehityksessä pitkällä aikavälillä säilyttäen palvelun yhtenäisen ilmeen ja mahdollistaen uusien ominaisuuksien kehittämisen aikaisemmin toteutettuja osia hyödyntäen. Dokumentoidut työskentelytavat yhdistävät designereitä ja kehittäjiä, sekä helpottavat uusien ihmisten mukaantuloa projektiin.

Käyttöliittymän erottaminen muusta ohjelmistologiikasta mahdollistaa käyttöliittymäkomponenttien kehityksen ja testauksen erillään, sekä parantaa komponenttien uudelleenkäytettävyyttä. Storybookin tai vastaavan työkalun käyttäminen osana front end -kehitystyötä auttaa kehittäjää ohjelmiston uusien ominaisuuksien toteutuksessa havainnollistamalla komponentin eri variaatioissa tapahtuvat muutokset. Storybookin monipuolisilla lisäosilla sekä visuaalisen testauksen integraatiolla työkalua voidaan mukauttaa projektin tarpeisiin.

LÄHTEET

• Atlassian. n.d. Design system template. Verkkosivu. Viitattu 25.9.2023.
  https://www.atlassian.com/software/confluence/templates/design-system
• Chan, M. 2023. How to Test UI AUTOMATICALLY — Storybook and Chromatic. YouTube-video. Julkaisija Chromatic 3.5.2023. Viitattu 7.9.2023.
  https://www.youtube.com/watch?v=zhrboql8UuU
• Chromatic. n.d.a. Publish Storybook to review. Verkkosivu. Viitattu 7.9.2023.
  https://www.chromatic.com/features/publish
• Chromatic. n.d.b. TurboSnap. Verkkosivu. Viitattu 6.11.2023.
  https://www.chromatic.com/docs/turbosnap/
• Figma. 22.6.2023. Config 2023 Product Launch Keynote - Dylan Field, Kris Rasmussen. Video. Viitattu 15.11.2023.
  https://www.youtube.com/watch?v=yI9QVwkk2Go
• Cubilla, J. 2022. Design Systems: Introduction. Koulutustallenne. Julkaistu 22.4.2023. Alma Media. Viitattu 25.9.2023.
• Nevanperä, L. 2022. Storybook Driven Development. Koulutustallenne. Julkaistu 24.5.2023. Alma Media. Viitattu 25.9.2023.
• Fox, B. 8.5.2021. Atomic Design for Developers: Better Component Composition and Organization. Verkkosivu. Viitattu 8.9.2023.
  https://benjaminwfox.com/blog/tech/atomic-design-for-developers
• Frost, B. 2016a. Designing Systems. E-kirja. Viitattu 8.9.2023.
  https://atomicdesign.bradfrost.com/chapter-1/
• Frost, B. 2016b. Atomic Design Methodology. E-kirja. Viitattu 8.9.2023.
  https://atomicdesign.bradfrost.com/chapter-2/
• Frost, B. 10.7.2019. Extending Atomic Design. Blogi. Viitattu 1.11.2023
  https://bradfrost.com/blog/post/extending-atomic-design/
• Google. n.d. Key frameworks in UX design. Video. Viitattu 14.11.2023.
  https://www.coursera.org/learn/foundations-user-experience-design/lecture/8SoMF
• Invalidiliitto. n.d. Saavutettavuus. Verkkosivu. Viitattu 7.9.2023.
  https://www.invalidiliitto.fi/esteettomyys/saavutettavuus
• LähiTapiola. 2023. Design Tokens. Verkkosivu. Viitattu 12.10.2023.
  https://www.duetds.com/tokens/
• Material UI. n.d. Default theme viewer. Verkkosivu. Viitattu 12.10.2023.
  https://mui.com/material-ui/customization/default-theme/
• Munawar, M. 7.6.2023. Atomic Design system implementation using Storybook. Verkkosivu. Viitattu 8.9.2023.
  https://blogs.halodoc.io/atomic-design-system-implementation-at-halodoc/
• Orozco, E. 23.3.2022. Speed, Consistency, and Scalability: The 3 Pillars of Design Systems. Verkkosivu. Viitattu 25.9.2023.
  https://www.edorozco.com/speed-consistency-and-scalability-the-3-pillars-of-design-systems/
• SemiDesign. 2.8.2022. How We Test Semi Design Component Libraries. Verkkosivu. Viitattu 21.10.2023.
  https://medium.com/front-end-weekly/how-we-test-semi-design-component-libraries-64b854f63b65
• Storybook. n.d.a Why Storybook?. Verkkosivu. Viitattu 7.9.2023.
  https://storybook.js.org/docs/react/get-started/why-storybook
• Storybook. n.d.b Essential Addons. Verkkosivu. Viitattu 21.10.2023.
  https://storybook.js.org/docs/react/essentials/introduction
• Storybook. n.d.c Storybook Addons. Verkkosivu. Viitattu 21.10.2023.
  https://storybook.js.org/docs/react/configure/storybook-addons
• Storybookjs. n.d.d Accessibility Addon. Verkkosivu. Viitattu 7.9.2023.
  https://storybook.js.org/addons/@storybook/addon-a11y
• Somers, M. 9.9.2015. A Maturity Model for Design Systems. Blogi. Viitattu 25.9.2023.
  https://medium.com/slalom-build/a-maturity-model-for-design-systems-93fff522c3ba
• Wunder. n.d. Design systemit. Verkkosivu. Viitattu 25.9.2023.
  https://wunder.io/fi/wunderpedia/teknologia/design-systemit/

LIITTEET

Kaikki esimerkeissä käytetty lähdekoodi on julkaistu osoitteessa
https://github.com/AkiKurvinen/nextjs-storybook-chromatic-template

Figma template - Atomic Design Workflow
https://www.figma.com/community/file/1304079459895956066

• Liite 1. OldStockPanel.tsx
• Liite 2: OldStockPanel.module.css
• Liite 3: StockPanelController.tsx
• Liite 4: StockPanelView.tsx
• Liite 5: Figure.tsx
• Liite 6: StockList.tsx
• Liite 7: StockItem.tsx