Miten luoda Living Style -opas

Elävän tyylin oppaan (LSG) käyttäminen kehityksen edistämisessä on käytäntö, joka saa paljon suosiota, koska sillä on monia etuja, kuten koodin tehokkuus ja UI-yhdenmukaisuus. Mutta miten voit luoda sen? Mitä sinun pitäisi sisällyttää? Ja mistä aloittaisit? Tässä opetusohjelmassa käsittelen nitty-gritty yksityiskohtia luoda elantonsa käyttäen DocumentCSS .

The Beauty of Living tyylioppaita

Vakiotyylin tavoin elävän tyylin oppaassa on joukko standardeja sovellusten tyylien käyttämiseksi ja luomiseksi. Vakiomuotoisen oppaan tapauksessa tavoitteena on säilyttää brändin yhtenäisyys ja estää grafiikan ja muotoilun väärinkäyttö. Samalla tavalla LSG: itä käytetään ylläpitämään sovelluksen johdonmukaisuutta ja ohjaamaan niiden toteuttamista. Mutta mikä tekee LSG: stä erilaisen ja tehokkaamman, se on, että suuri osa sen tiedoista lähtee lähdekoodista, mikä tekee siitä helppoa ja tehokasta kuvastaa sovelluksen kehittymistilaa.

Jopa tänään on mielessä puhua oppia, että voit käyttää sovelluksen lähdekoodia tyyliohjeesi rakentamiseen.

Jos tarkastelet alla olevia esimerkkejä, näet LSG: n yhteiset nimittäjät:

• Luettelo asiakirjoista
• Lyhyt dokumentaatio, jossa on koodinpätkiä ja interaktiivisia käyttöliittymiä koskevat demonstraatiot

Lonely Planet Style -oppaasta

Sales Force Style -oppaassa

LSG: n toinen keskeinen osa on se, että voit käyttää tyyliohjeiden generaattoria automatisoimaan prosessia. Tyyliopasgeneraattori käyttää sovelluksen lähdekoodia syöttääkseen suurimman osan LSG-dokumentaatiosta ja seuraa koodissasi tapahtuneita muutoksia ja huolehtii siitä, että tyylitietoasiakirjat päivitetään hakemuksesi muutoksiin.

Tyyliohjeiden generaattorit

Valittavissa on monia makuja, riippuen koodin kielestä, jonka haluat dokumentoida tai projektin määrityksestä. Seuraavassa on joitain paikkoja etsimään vaihtoehtoja:

• Syvällinen yleiskatsaus Living Style Guide Tools -työkaluista , Robert Haritonov, Smashing -lehti
• Katsaus mallikirjaston generaattoreihin , David Hund, GitHub
• Style Guide Generator Roundup , Susan Robertson, A List Apart
• Tyylioppaatyökalut , Sivuston tyyliohjeisiin

Tässä opetusohjelmassa näytän sinulle, kuinka voit käyttää DocumentCSS: ää LSG: n luomiseen. Bitovi on luonut tämän työkalun avoimen lähdekoodin ja sitä voidaan käyttää missä tahansa projektissa CSS: n dokumentoimiseksi (esim. Less ja SASS tukevat esikäsittelyohjelmat). Jos olet kiinnostunut dokumentoimasta Javascriptia ja muita kieliä, voit helposti tehdä sen DocumentCSS: llä, koska tämä työkalu on DocumentJS: n osajoukko. En peitä tätä osaa tässä opetusohjelmassa, mutta on hyvä muistaa.

Suunnittele tyylioppaasi

Ennen sukellusta LSG: n luomiseen ensimmäinen vaihe on suunnitella, mitä siinä on. Kuten mikä tahansa hyvä sivusto, hyvin jäsennelty informaatiorakenne (IE) on avain.

Aloitetaan siis käyttämällä seuraavia esimerkkikoosteita "Vintage Shop" -sovelluksistamme ja tarkkailemalla käyttöliittymän pysyviä elementtejä:

Vintage Shop Mockups

Tässä vaiheessa suosittelen aloittaa suuremmilla elementtiryhmillä, kuten navigoinnilla, kärryllä tai lomakkeilla. Esimerkiksi erotamme suunnittelun näistä kolmesta ryhmästä: vaiheet, mini-ostoskorin ja ostoskorin tuotteet:

Näiden suurempien elementtiryhmien avulla voit aloittaa tarkemmin ja tunnistaa jatkuvat "tyylit". Esimerkiksi typografiaa koskeva yleissopimus ja erityisesti otsikot, alanimikkeet ja linkit vs. säännöllinen teksti on yleissopimus. Painikkeiden väri näkyy myös sivuilla.

Kun kirjoitat kaikki yhteen, merkitään nämä ryhmät kaavion avulla:

Tarkempia tarkasteluja näihin ryhmiin voit hienosäätää niitä ja muuttaa ne luokkiin, joita voit käyttää tyyliohjeesi kasvaessa. Esimerkiksi:

• "Elements" on hyvin epämääräinen termi, joka voi viitata mihin tahansa HTML-elementtiin, joten tämän ryhmän parempi nimi voisi olla "Komponentit" tai "Moduulit". Nämä ovat edelleen laajoja termejä, mutta ne ovat tarkempia elementtien luonteessa, jotka kattavat.
• "Ensisijainen vs. toissijainen" -painikkeet voivat olla osa "Base Elements" -tekstiä, ja sen väriosa voi mennä "Color Palette" -luokan sisälle.

Lisäksi voit ajatella kategoriaa, johon voit lisätä yleisempää tietoa tyyliohjeestasi. Hyvä esimerkki tästä olisi oppaat-osio, jossa voit kuvata, miten voit osallistua tyyliohjeeseen tai brändäysosaan, jossa voit sisällyttää tuotemerkkiin liittyviä ohjeita, jotka on pidettävä mielessäsi sovelluksen suunnittelussa ja toteutuksessa.

Tässä mielessä tässä kuvio näyttää:

Näet tämän kaavion muodostavan sivustokartan, joka on pohjimmiltaan mitä haluat käyttää suunnitelta luodessasi elävän tyylin oppaasi.

Nyt voit sukeltaa malleihin ja piirtää oman sivustokartan, mukaan lukien niin monta luokkaa kuin luulet olevan hyödyllistä tulevaisuudessa. Voit saada ideoita muista tyylisuunnista ( styleguides.io/examples on suuri resurssi). Kun olet valmis, tarkista tämä kattavampi versio ja vertaile sitä.

Sivun luominen Living Style -oppaasta

Vaikka suurimman osan LSG-dokumentaatiosta tulee lähdekoodin lisäämääsi erityisiä kommentteja, voit myös luoda erillisiä sivuja, joilla voit hallinnoida muita sisältötyyppejä, jotka eivät liity koodiin (ajattele suunnitteluperiaatteita, esteettömyysohjeita, tai vedä pyyntöohjeita). Tämä antaa sinulle etuna asiakirjojen keskittämisen yhteen paikkaan: sovellustasi asumismuoto oppaan.

Voisit melkein ajatella elävän tyylin oppaan sovelluksesi "pelisäännöt". "Säännön" sisällä on kaikki tarvittavat tiedot pelin "pelattavaksi": Rakennuspalikat ja säännöt uusien lohkojen luomiseen ja rakentamiseen. Sisällytä, miten muut tiimisi jäsenet voivat osallistua siihen ja auttaa pitämään sitä elävänä asiakirjana.

_{Yas! Usko se. Voit saada kaikki asiakirjasi yhteen paikkaan!}

Tässä mielessä aloitetaan asentamalla näytehakemus, jota käytämme tässä opetusohjelmassa.

Näytesovelluksen asentaminen

Asennusprosessissa on kolme vaihetta:

1. Solmun asentaminen

Ensinnäkin varmista, että olet Solmu asennettu. Tarvitset ainakin version 6.

2. Sovelluksen asentaminen

Lataa sitten tämä zip-tiedosto: sgdd-tutorial.zip työpöydälle ja purkaa sen pakkaus . Tämä on tärkeää, koska toinen sijainti rikkoisi asennuskomentoja.

Avaa sitten päätelaite ja anna seuraava komento:

cd ~/Desktop/vintage-shop-sgdd-tutorial && npm install

Sovelluksen ja sen riippuvuuksien asentaminen kestää muutaman sekunnin.

3. App

Kun asennus on valmis, kirjoita seuraavat komennot:

1. npm run develop
2. Uuteen välilehteen kirjoitetaan: npm run document

Nyt rikkoa tämä alas:

npm run develop

Aloittaa palvelimen, jossa voit nähdä sovelluksesi käynnissä osoitteessa: http://localhost: 8080. Näet terminaalissa:

Selaimessa:

npm run document

Luo elävän tyylin oppaan osoitteessa http://localhost: 8080 / tyyliopas. Voit lisätä lipun -- -w tämän komennon avulla voit tarkkailla koodisi muutoksia ja luoda päivityksen elävän tyylin oppaassa, kuten:

npm run document -- -w

Siirtyminen selaimeen sinun pitäisi nähdä:

Luotu elävä tyyliopas käyttää DocumentCSS , joten katsokaamme, miten tämä toimii.

Miten DocumentCSS toimii?

DocumentCSS on staattinen sivuston generaattori. Tämä tarkoittaa, että se etsii koodinne muotoillut kommentit ja luo staattisen verkkosivuston. Tätä sivustoa kutsutaan "staattiseksi", koska se pysyy ennallaan, kunnes komento (tässä tapauksessa documentjs ) ajetaan uudelleen. Tämä työnkulku toimii hyvin elävän tyylin oppaan luomiseksi, koska tyylitiedostosi muutokset ovat myös muutoksia Living Style Guide -standardisivustoon.

Luodaksesi asumismuotoisen oppaan, DocumentCSS tekee seuraavat:

• Lukee kokoonpanossa määritettyjä tiedostoja (tämä opetusohjelma tarkastelee sitä .less ja .md tiedostot)
• Etsii kommentteja, joissa käytetään erityisiä "tunnisteita" (kuten @page , @stylesheet tai @styles .
• Luo html-tiedostoja ja liittää ne sivuston rakentamiseen.

Tässä mielessä hypätä DocumentCSS: n avulla luodaksesi uuden sivun LSG: ssä.

Sivun luominen

Aloita ensin avaamalla sovellusohjelma koodinmuokkaimessa. Sinun pitäisi nähdä seuraava tiedostorakenne:

Poraa src ja löydä base/markdown . Täältä löydät sivuja, jotka ovat jo tyyliohjeessa. Luo uusi markdown-tiedosto ja nimeä se "noin" (laajennuksella .md ). Tiedostorakenteen pitäisi nyt näyttää tältä:

Lisää tämän uuden tiedoston sisälle tunniste @page jota seuraavat kaksi merkkijonoa:

@page about about

Nyt rikkoa tämä alas:

@page

Tunniste @page ilmoittaa tiedoston sivuna ja kertoo DocumentCSS: lle, että tämän tiedoston tiedot olisi näytettävä tyylioppaan sivuna. Tämä erottelee sen dokumenttitiedostosta, javascriptistä tai muista tiedostomuodoista.

about

Tämä on sivun yksilöllinen nimi ja sitä käytetään viittauksena muihin tunnisteisiin. Joten pitää se lyhyt, pieni ja yksinkertainen, koska sitä käytetään sivun urlina. Esimerkiksi uuden sivun URL-osoite on: http://localhost: 8080 / tyyliopas / about.html

About

Tämä on sivun otsikko, jota käytetään luodussa sivustossa näyttötarkoituksiin. Tässä voit käyttää useita sanoja, joissa on välilyöntejä tai muita merkkejä.

Voit tarkastella äskettäin luotuja sivunäytönohjaimia uudelleen päätelaitteessa (paitsi jos sinulla on tarkistuksia) ja siirry sitten http://localhost: 8080 / tyyliopas / about.html nähdäksesi uuden sivun.

Seuraava vaihe on lisätä sivusi navigointiin. Tällöin lisää tiedostoon toinen rivi seuraavasti:

@page about About@parent index

Tunniste @parent voit määrittää asiakirjaasi vanhemman. Tässä tapauksessa haluamme, että "Tietoja" -sivu tulee näkyviin kotisivun alla. Nyt voit aloittaa asiakirjat uudelleen ja nähdä, että sivu näkyy Welcome-linkin alapuolella:

Ja jos klikkaat "Tervetuloa" -linkkiä, pääset aloitusnäyttöön:

Nyt olemme hyviä lisätä sisältöä tälle sivulle käyttämällä markdownia tai html-tiedostoa. Lisää harjoituksesi loppuun seuraavasti:

@page about About@parent index## Hello World!This is the first page of my style guide. Here I can add any type of content that shouldn’t live with the code. Like who are the main contributors of the style guide or contact info.For example here's an animated gif inside of an `iframe`:

Ja tässä on tuotos:

Tyylitaulukon dokumentointi Living Style -oppaassa

LSG: n luomisen ydin on kyky laittaa dokumentaatiosi oikealle, mihin se kuuluu: lähdekoodissa. On todennäköistä, että dokumentoit jo koodisi, joka on loistava tilaisuus viedä se seuraavalle tasolle käyttämällä tyyliopasgeneraattoria, joka voi ottaa nämä kommentit järjestettyyn sivustoon ja antaa muille (ja itsestäsi tulevaisuudesta) tietää miksi ja mitä koodissa on tehty.

Itse tulevaisuudesta lukemalla asiakirjoja, jotka kirjoitit aiemmin.

Tyylitaulukon dokumentointi

Tyylitaulukon dokumentointi seuraa samanlaista mallia sivun dokumentointi , mutta tässä tapauksessa dokumentaatio tulee sisälle kommenttiin, aivan koodin vieressä (se on kauneus!).

Aloita avaamalla stylesheet: buttons-custom.less .

Lisää tämän tiedoston sisälle ja kommenttilohkon sisälle tunniste @stylesheet jota seuraavat kaksi merkkijonoa:

/**@stylesheet buttons.less Buttons*/

Huomaa, että dokumentaation kommentti on aloitettava /** parserille (tässä tapauksessa JSDoc ) tunnistamaan sen.

Nyt rikkoa tämä alas:

@stylesheet

Tunniste @stylesheet ilmoittaa tiedoston tyylitaulukoksi ja kertoo DocumentCSS että tämän tiedoston tiedot olisi näytettävä tyyliohjeessa. Tämä auttaa erottamaan sen muun tyyppisistä asiakirjoista, kuten sivuista, osista ja malleista. ( lue täältä täydellinen luettelo asiakirjatyypeistä ).

buttons.less

Tämä on tyylitietokannan yksilöllinen nimi ja sitä käytetään viittauksena muihin tunnisteisiin. Vaikka voit käyttää minkä tyyppistä nimeä, suosittelen käyttämään tyylitiedosto-tiedoston nimeä, koska se auttaa tiedoston löytämisessä dokumentoinnin yhteydessä. Muista, että tämä vaikuttaa asiakirjan url-osoitteeseen. Tässä esimerkissä url on: http://localhost: 8080 / tyyliopas / buttons.less.html

Buttons

Samanlainen sivun luominen , tämä on tyylitaulukon otsikko, jota käytetään näytettyihin tarkoituksiin generoidussa sivustossa. Tässä voit käyttää useita sanoja, joissa on välilyöntejä tai muita merkkejä.

Voit tarkastella äskettäin luotua sivua seuraavasti:

documentjs

Ja sitten mene http://localhost: 8080 / tyyliopas / buttons.less.html nähdäksesi uuden sivun.

Lisää nyt uusi dokumentti navigointiin. Tätä varten noudatamme samaa yleissopimusta, jota käytimme, kun luotiimme sivun @parent tag:

/*** @stylesheet buttons.less Buttons* @parent styles.base*/

Huomaa, että tässä tapauksessa olemme lisänneet .base että sivun pitäisi näkyä sivupalkissa näkyvässä ryhmässä "Baseline" (voit luoda myös aliverkon ryhmiä!).

Asiakirjojen uudelleenkäsittely ja sivun päivittäminen pitäisi näyttää tältä:

Nyt lihavalle osalle! Sivustomme avulla voimme tehdä muutamia asioita:

• Voimme lisätä asiakirjan yleisen kuvauksen
• Voimme lisätä kaikenlaisia ​​sisältöjä sekä markdownin että pelkkään HTML-muotoon
• Ja mikä parasta, voimme lisätä demoja koodimme käyttöön?

Lisätään lyhyt kuvaus ja esittely painikkeillemme doc:

/*** @stylesheet buttons.less Buttons* @parent styles.base* @description* Global style definitions for all button elements.* @iframe src/base/bootstrap-custom/buttons/buttons-custom.html*/

Toista asiakirja uudelleen ja?:

Kuten voit nähdä @iframe tunnisteen avulla voit lisätä iframe-tiedoston dokumentointiasi. Tämä demo on oikeastaan ​​vain yksinkertainen html-tiedosto, jossa on komentotunniste, joka tuo sovelluksesi CSS: n suoritusaikaan.

Avaa demo buttons-custom.html  :

Katso, miten koodi näyttää:

<script src="/node_modules/steal/steal.js" main="can/view/autorender/"><import "vintage-shop/styles.less";script> <a class="btn btn-default" href="#" role="button">Linka><button class="btn btn-default" type="submit">Buttonbutton><input class="btn btn-default" type="button" value="Input"><input class="btn btn-default" type="submit" value="Submit"><hr /><button type="button" class="btn btn-default">Defaultbutton><button type="button" class="btn btn-primary btn-checkout">Primarybutton><button type="button" class="btn btn-success">Successbutton><button type="button" class="btn btn-info">Infobutton><button type="button" class="btn btn-warning">Warningbutton><button type="button" class="btn btn-danger">Dangerbutton><button type="button" class="btn btn-link">Linkbutton>

Ainoa tässä tiedostossa tarvittava asia on komentotunniste, jonka pitäisi olla sama kaikille tässä sovelluksessa luotuasi demoon. Loput koodista ovat merkinnät tyylillä, jotka haluat näyttää demossa.

Lisäksi voit käyttää tunnistetta @demo näyttää myös siinä käytettävän koodinpätkän. Kuten tämä:

/*** @stylesheet buttons.less Buttons* @parent styles.base** @description* Global style definitions for all button elements.* @demo src/base/bootstrap-custom/buttons/buttons-custom.html*/

Mikä tuottaa näin:

Demos-luotto menee Bootstrap-dokumentit jossa napsautamme koodin.

Nyt, ennen kuin siirryt banaaneihin tämän kanssa, on pari muuta herkkua, joita voit hyödyntää:

• Tyyliosastojen luominen
• Stylesheet-ryhmien luominen

Tyyliosastojen luominen

Voit luoda tyyliosion käyttämällä tunnistetta @styles . Tämä tunniste on suloinen, koska sen avulla voit jakaa tyylitietokirjaasi järkeviin palasiksi, joista voit puhua ja ymmärtää paremmin.

Esimerkiksi esimerkissämme meillä on tyylit painikkeiden määrittämiseen yleensä, riippumatta käytetystä merkinnästä (joko a vs tag). Ja sitten meillä on määritelmiä väristä. Kanssa @styles tunnisteen avulla voimme rikkoa värimääritelmät omiin osiinsa, puhumatta niistä erikseen, mutta voidaksemme hyperlinkkiä suoraan kyseiseen osioon.

Näin se toimii. Samassa tiedostossa buttons-custom.less , aiomme lisätä tagin @styles heti ensimmäisen tyyliluokan jälkeen ja ennen värimuuttujia. Näin se pitäisi näyttää:

/*** @stylesheet buttons.less Buttons* @parent styles.base** @description* Global style definitions for all button elements.* @demo src/base/bootstrap-custom/buttons/buttons-types.html*/.btn {display: inline-block;...}/*** @styles buttons-colors Button Colors** @description* Buttons can be displayed in the following colors:* @demo src/base/bootstrap-custom/buttons/buttons-color.html*/@btn-default-color: #333;

Tässä on muutamia asioita:

• Päivitin ensimmäisen demo-ohjelman näyttämään vain painotyypit.
• Lisäsin uuden kommenttilohkon käyttämällä @styles tag. Täällä annan sille ainutkertaisen nimen button-colors ja otsikko Button Colors . Annoin sen myös a @description ja lisätään a @demo sillä se näyttää vain painikkeen värit.

Ja tässä on tuotos:

Huomaa, että uusi kommentointilohko on nyt "Buttons" -dokumentin osio, johon voit myös käyttää suoraan tätä URL-osoitetta: http://localhost: 8080 / styleguide / buttons-colors.html

Henkilökohtaisesti tämä on erittäin hyödyllinen, koska voit viitata ihmisiin tyyliohjeen tiettyyn osaan, vs sanomalla: " on x-sivulla x-osan alla, niin sinun täytyy selata ... ja blah, blah, blah ". Sen sijaan voit tarjota suoran linkin siihen ja tarinan loppuun.

Stylesheet-ryhmien luominen

Lisäksi voit luoda osioita tai ryhmiä tyylioppaan sivupalkissa. Avaa tiedosto tähän styles.md , joka sijaitsee markdown hakemistoon.

Huomaat tässä uuden nimimerkin @group .

@page styles Styles@group styles.theme 0 Theme@group styles.base 1 BaselineThe styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.

Nyt rikkoa toinen rivi:

@group

@group tag allows you to create a section in the sidebar that appears under the parent section. tunnisteen avulla voit luoda osion sivupalkissa, joka näkyy emoyhtiössä. Esimerkiksi ryhmät: "Teema" ja "Baseline" näkyvät "Tyylit" -osiossa.

styles.theme

Tämä on ryhmän ainutkertainen nimi. Hyvä käytäntö tässä on käyttää emoyhtiön nimen, tässä tapauksessa "Tyylit" nimeä nimitilassa. Tällä tavoin, jos haluat luoda toisen ryhmän, jolla on sama nimi, mutta toisen osan alla, ryhmän nimi säilyy ainutlaatuisena.

0

Tämä on järjestys, jossa ryhmän tulee näkyä, joka alkaa numerolla 0. Jos tilausta ei ole annettu, ryhmien luettelo näytetään aakkosjärjestyksessä.

Theme

Tämä on varsinainen nimi, joka näkyy sivupalkissa, joten voit käyttää useita sanoja, joissa on välilyöntejä ja muita merkkejä.

Voit nähdä ryhmät toiminnassa lisäämällä uusi ryhmä seuraavasti:

@page styles Styles@group styles.theme 0 Theme@group styles.base 1 Baseline@group styles.forms 2 FormsThe styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.

Lopuksi lisätään olemassa oleva asiakirja tähän uuteen jaksoon. Tällöin avaa tiedosto forms-custom.less :

Ja rivillä 3, vaihda styles.base varten styles.forms .

/*** @stylesheet forms-custom.less Form Elements* @parent styles.forms**/

Suorita sitten asiakirjat ja päivitä selain. Näet nyt "Muotoelementit" -dokumentin sivupalkin ryhmässä "Lomakkeet".

Paketoida

Living Style Guides on työkalu, jolla luodaan johdonmukaisempi ja yhtenäisempi käyttöliittymä, ja voit todella hyödyntää niitä sovellettaessa Tyylioppaasta kehitettyä lähestymistapaa ja kun suunnitellaan modulaarisella tavalla .

Sinä, rakennat asumismuotoja tässä vaiheessa!

Tässä vaiheessa, jos olet seurannut mukana, sinulla on nyt k?

dokumentointi dokumentointi css elävä tyyli opas LSG tyylioppaat