Hvernig Til Skapa Stílhreinar Guide

Notkun lifandi stíll fylgja (LSG) til að keyra þróun er æfa sem er að ná miklum vinsældum vegna þess að það hefur marga kosti, þar á meðal kóða skilvirkni og UI samræmi. En hvernig geturðu búið til einn? Hvað ættirðu að fela í sér? Og hvar byrjarðu jafnvel? Í þessari einkatími mun ég grípa inn í nitty-gritty upplýsingar um að búa til lifandi stíl með DocumentCSS .

The Beauty of Living Style Guides

Líkt og venjulegt stíll fylgja, lifandi stíl fylgja veitir sett af stöðlum fyrir notkun og stofnun stíll fyrir umsókn. Þegar um er að ræða staðalstílleiðbeiningar er tilgangurinn að viðhalda samhæfingu vörumerkis og koma í veg fyrir misnotkun á grafík og hönnunarþætti. Á sama hátt eru LSGs notuð til að viðhalda samræmi í umsókn og leiðbeina framkvæmd þeirra. En það sem gerir LSG mismunandi og öflugra er að mikið af upplýsingum hennar kemur beint frá upprunakóðanum, sem gerir það auðvelt og skilvirkt að endurspegla þróunarástand umsóknar.

Jafnvel í dag er það huga að blása til að læra að hægt sé að nota upprunakóðann af umsókn þinni til að byggja upp stílhandbókina þína.

Ef þú lítur á dæmin hér að neðan muntu sjá sameiginlega heiti LSG eru:

• Listi yfir þau atriði sem eru skjalfest
• Succinct skjöl með kóða sneiðar og gagnvirk UI sýnikennslu

Lonely Planet Style Guide

Sala Force Style Guide

Annað lykilatriði í LSG er að þú getur notað stýrileiðara rafall til að gera sjálfvirkan vinnslu. Stíll fylgja rafall mun nota umsókn uppspretta merkjamál til að fæða megnið af LSG skjölunum þínum og horfa á allar breytingar sem gerðar eru í kóðanum þínum, gæta þess að uppfæra skjal leiðbeiningar skjal eins og umsókn þín breytist.

Style Guide Generators

Það eru margar bragðir að velja úr, allt eftir því tungumáli sem þú vilt skrá eða uppsetningu verkefnisins. Hér eru nokkrar staðir til að leita að valkostum:

• Yfirgripsmikil yfirlit yfir Vinnustíl Guide Guide , Robert Haritonov, Smashing Magazine
• Yfirlit yfir Pattern Library Generators , David Hund, GitHub
• Style Guide Generator Roundup , Susan Robertson, A List Apart
• Style Guide Tools , Website Style Guide Resources

Fyrir þessa einkatími mun ég sýna þér hvernig þú getur notað DocumentCSS til að búa til LSG. Þetta tól búin til af Bitovi er opinn uppspretta og hægt að nota í hvaða verkefni sem er til að skjalfesta CSS (forvinnsluforrit eins og minna og SASS eru einnig studdar). Ef þú hefur áhuga á að skjalfesta Javascript og önnur tungumál getur þú auðveldlega gert það með DocumentCSS, þar sem þetta tól er hluti af DocumentJS. Ég mun ekki ná þessum hluta í þessari einkatími en það er gott að hafa í huga.

Skipuleggðu stílhandbókina þína

Áður en köfunin er búin til að búa til LSG er fyrsta skrefið að skipuleggja hvað verður í því. Eins og allir góðir viðbætur er vel skipulagt upplýsinga arkitektúr (IE) lykillinn.

Svo skulum byrja með því að nota eftirfarandi sett af hönnun sýnishornsins sem heitir "Vintage Shop" og fylgjast með viðvarandi þætti í UI:

Vintage Shop Mockups

Á þessum tímapunkti mælum við með að byrja með stærri hópa þætti, svo sem siglingar, vagninn eða eyðublöðin. Til dæmis munum við skilja hönnunina okkar í þessum þremur hópum: stígvísinn, lítill vagninn og vörurnar í körfunni:

Með þessum stærri hópum þætti getur þú byrjað að fara í smáatriði og skilgreina "stíl" sem viðvarandi. Til dæmis er samningur fyrir leturgerð almennt, og sérstaklega fyrir fyrirsagnirnar, undirfyrirsagnirnar og tenglana samanborið við venjulegan texta. Litur hnappanna heldur einnig áfram á síðum.

Taka saman allt saman, skulum skrifa niður þessar hópa með því að nota skýringarmynd:

Ef þú hefur dýpri skoðun á þessum hópum getur þú fínstillt þau og breytt þeim í flokka sem þú getur notað í stýrihandbókinni þinni eins og hún vex. Til dæmis:

• "Elements" er mjög óljós hugtak sem gæti vísað til hvaða HTML frumefni sem er, þannig að betra nafn fyrir þennan hóp gæti verið "hluti" eða "einingar. Þetta eru enn víðtækar skilmálar en eru nákvæmari í eðli þeirra þátta sem myndu ná til.
• "Primary vs Secondary" hnappar gætu verið hluti af "Base Elements" og litaspjaldið gæti farið inn í "Color Palette" flokk.

Að auki getur þú hugsað um flokk þar sem þú getur falið í sér fleiri almennar upplýsingar um stílhandbókina þína. Gott dæmi um það væri hluti af "Guides" þar sem þú gætir lýst hvernig þú getur stuðlað að stílhandbókinni eða "merkingu" þar sem þú getur sett viðmið um vörumerkið þitt sem ætti að hafa í huga þegar þú útskýrir og útfærir forritið þitt.

Með þetta í huga, hér er það sem skýringin myndi líta út:

Þú getur séð hvernig þetta skýringarmynd tekur lögun svæðiskorta, sem er í grundvallaratriðum það sem þú vilt nota sem áætlun þegar þú býrð til lifandi stíll fylgja.

Nú kafa inn í hönnunina og skissa upp eigin kortið þitt, þar á meðal eins margar flokkar og þú telur að væri gagnlegt fyrir framtíðina. Þú getur fengið hugmyndir frá öðrum leiðsögumönnum ( styleguides.io/examples er frábær auðlind). Þegar þú ert búinn skaltu skoða þessa stærri útgáfu og bera saman.

Búa til síður í Living Style Guide

Þó að megnið af LSG skjölunum þínum muni koma frá sérstökum athugasemdum sem þú bætir við kóðann getur þú einnig búið til sjálfstæðan síður þar sem þú getur hýst öðrum tegundum efnis sem ekki er sérstaklega við kóðann (hugsaðu um meginreglur um hönnun, eða draga beiðni leiðbeiningar). Þetta gefur þér kostur á að miðla skjölum þínum á einum stað: umsókn þína um lifandi stíl fylgja.

Þú gætir næstum hugsað um lifandi stílhandbókina sem "leikreglur" í forritinu þínu. Inni í "reglunum" eru allar upplýsingar sem þarf um hvernig á að "leika" leikinn: Byggingin og reglurnar um að búa til og byggja upp nýjar blokkir. Þar með talið hvernig aðrir meðlimir liðsins geta lagt sitt af mörkum og hjálpað til við að viðhalda því sem lifandi skjal.

_{Yas! Trúðu því. Þú getur haft öll skjölin þín sameinuð á einum stað!}

Með þessu í huga, skulum byrja með því að setja upp sýnishorn forritið sem við munum nota fyrir þessa kennslu.

Setja upp sýnishorn

Uppsetningarferlið hefur 3 skref:

1. Setja upp hnút

Fyrst skaltu ganga úr skugga um að þú hafir Hnút uppsett. Þú þarft að minnsta kosti útgáfu 6.

2. Setja upp forritið

Síðan skaltu sækja þessa zip skrá: sgdd-tutorial.zip á skjáborðinu þínu og slepptu því . Þetta er mikilvægt þar sem annar staður myndi brjóta uppsetningarskipanirnar.

Opnaðu síðan flugstöðina og sláðu inn eftirfarandi skipun:

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

Það tekur nokkrar sekúndur að setja upp forritið og ósjálfstæði hennar.

3. Running the App

Þegar uppsetningu er lokið skaltu slá inn eftirfarandi skipanir:

1. npm run develop
2. Í nýjum flipi sláðu inn: npm run document

Nú skulum brjóta þetta niður:

npm run develop

Byrjar miðlara þar sem þú getur séð forritið þitt keyra á: http://localhost: 8080. Þú munt sjá í flugstöðinni:

Og í vafranum:

npm run document

Býr til lifandi stíll handbókar á http://localhost: 8080 / styleguide. Þú getur bætt við fánanum -- -w til þessarar skipunar að horfa á breytingar á kóðanum þínum og síðan búa til uppfærslu í lifandi stílhandbókinni, eins og this:

npm run document -- -w

Skipta yfir í vafrann sem þú ættir að sjá:

The mynda lifandi stíl fylgja notar DocumentCSS , svo skulum kíkja á hvernig virkar þetta.

Hvernig virkar DocumentCSS?

DocumentCSS er truflanir staður rafall. Þetta þýðir að það leitar að sérstökum sniðum athugasemdum í kóðanum þínum og skapar kyrrstöðu vefsíðu. Þessi síða er kallað "truflanir" vegna þess að hún er óbreytt þar til stjórn (í þessu tilviki documentjs ) er keyrt aftur. Þessi vinnuflæði virkar vel til að búa til lifandi stýrihandbók þar sem breytingar á stílblöðunum þínum eru einnig breytingar á Stílhreinarhandbókinni.

Til að byggja upp lifandi stíl fylgja, DocumentCSS gerir eftirfarandi:

• Lesið í gegnum skrár sem eru tilgreindar í stillingum (fyrir þessa einkatími verður það að skoða .less og .md skrár)
• Útlit fyrir athugasemdir sem nota sérstaka "merkingar" (eins og @page , @stylesheet eða @styles .
• Býr til HTML skrár og tengir þá til að byggja upp síðuna.

Með þessu í huga, skulum við hoppa inn í DocumentCSS til að búa til nýja síðu í LSG.

Búa til síðu

Til að byrja skaltu opna sýnishornið í kóðaritlinum þínum. Þú ættir að sjá eftirfarandi skráareiningu:

Boraðu niður í src og finndu base/markdown . Hér finnur þú síður sem eru nú þegar til í stýrihandbókinni. Búðu til nýtt merkjaskrá og heitið það "um" (með viðbótinni .md ). Skrá uppbygging þín ætti nú að líta svona út:

Inni í þessari nýju skrá skaltu bæta merkinu við @page eftir tvo strengi:

@page about about

Nú skulum brjóta þetta niður:

@page

Merkið @page lýsir skránum sem síðu og segir DocumentCSS að upplýsingarnar í þessari skrá ætti að birtast sem síða í stílhandbókinni. Þetta þjónar til að greina það frá stíllheitum, javascript eða öðrum gerðum skráa í skjölunum þínum.

about

Þetta er einstakt heiti síðunnar og er notað sem tilvísun til annarra merkja. Svo halda því stuttum, lágstöfum og einföldum eins og það verður notað sem vefslóð fyrir síðuna. Fyrir dæmi okkar verður vefslóðin fyrir nýja síðuna okkar: http://localhost: 8080 / styleguide / about.html

About

Þetta er titill síðunnar sem verður notaður til birtingar á myndinni. Hér getur þú notað mörg orð með bilum eða öðrum stafi.

Til að skoða nýstofnaða síðu keyrðu documentjs í flugstöðinni aftur (nema þú hafir það að horfa á breytingar), og þá fara á http://localhost: 8080 / styleguide / about.html til að skoða nýja síðu.

Næsta skref er að bæta við síðunni þinni við leiðsögnina. Til þess að bæta við annarri línu við skrána sem hér segir:

@page about About@parent index

Merkið @parent leyfir að tilgreina foreldri fyrir skjalið þitt. Í þessu tilfelli viljum við að "Um" blaðsíðan birtist undir heimasíðunni. Nú er hægt að endurreisa skjölin og sjá blaðsíðuna birtast undir "Velkomin" tengilinn:

Og ef þú smellir á "Velkomin" tengilinn getur þú nálgast upphafssíðuna:

Nú erum við góðir að bæta við efni á þessari síðu með markdown eða html. Til að ljúka æfingu, skulum við bæta við eftirfarandi dummy efni:

@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`:

Og hér er framleiðsla:

Documenting a Stylesheet í Living Style Guide

Hjartaið að búa til LSG er hæfni til að setja skjölin þín rétt þar sem það tilheyrir: í kóðanum. Líkurnar eru á því að þú ert nú þegar að skrá kóðann þinn, sem er frábært tækifæri til að taka það á næsta stig með því að nota stýrileiðara sem getur breytt þessum athugasemdum á skipulögðu vefsvæði og látið aðra (og sjálfan þig frá framtíðinni) vita hvers vegna og hvað hefur verið gert í kóðanum.

Sjálfur frá framtíðinni eftir að hafa lesið skjölin sem þú skrifaðir í fortíðinni.

Skjalast sniðmát

Documenting a styleheet fylgir svipað mynstur við skjalfesta síðu , en í þessu tilviki munu skjölin fara inn í athugasemd, rétt við hliðina á kóðanum (það er fegurðin!).

Til að byrja að opna stíllinn: buttons-custom.less .

Inni í þessari skrá og inni í athugasemdareit skaltu bæta merkinu við @stylesheet eftir tvo strengi:

/**@stylesheet buttons.less Buttons*/

Athugaðu að skjalavinnsla þarf að byrja með /** fyrir persónuna (í þessu tilfelli JSDoc ) til að viðurkenna það.

Nú skulum brjóta þetta niður:

@stylesheet

Merkið @stylesheet lýsir skránum sem stíll og segir DocumentCSS að upplýsingarnar í þessari skrá ætti að birtast eins og í stílhandbókinni. Þetta þjónar til að greina frá öðrum gerðum skjala, eins og síður, hluti og módel, meðal annarra ( lesið hér um alla lista yfir gerðir skjala ).

buttons.less

Þetta er einstakt nafn stíllarkisins og er notað sem tilvísun til annarra merkja. Þó að þú getir notað hvaða tegund af heiti, þá mæli ég með því að nota nafnið á stílsíðu skráarinnar, þar sem þetta mun hjálpa til við að finna skrána þegar vísað er til skjala. Hafðu í huga að þetta mun hafa áhrif á vefslóð skjalsins. Fyrir þetta dæmi verður vefslóðin: http://localhost: 8080 / styleguide / buttons.less.html

Buttons

Svipað búa til síðu , þetta er titillinn á stílsniði sem verður notaður til birtingar á myndinni. Hér getur þú notað mörg orð með bilum eða öðrum stafi.

Til að skoða nýstofnaða síðu hlaupa eftirfarandi skipun nema þú hafir það að horfa á breytingar:):

documentjs

Og þá fara til http://localhost: 8080 / styleguide / buttons.less.html til að skoða nýja síðu.

Nú skulum við bæta þessu nýja skjali við flakk okkar. Fyrir þetta munum við fylgja sömu venju sem við notuðum þegar við búðum til síðuna með því að nota @parent tag:

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

Athugaðu að í þessu tilfelli höfum við bætt við .base Til að tilgreina þessa síðu ætti að birtast undir hópnum "Grunnlínu" sem er sýnt í skenkur (þú getur líka búið til hópa í subnav þínum! Við munum grafa í það smávegis).

Endurtaka skjölin og endurnýja síðuna ætti að líta svona út:

Nú fyrir kjötþáttinn! Með síðunni okkar í stað getum við gert nokkra hluti:

• Við getum bætt við almennri lýsingu fyrir skjalið
• Við getum bætt við alls konar efni með bæði merkingu eða einfaldan HTML
• Og best af öllu, getum við bætt við kynningum fyrir kóða okkar?

Við skulum bæta við fljótlegri lýsingu og kynningu fyrir hnappana okkar 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*/

Rerun skjölin og?:

Eins og þú getur séð @iframe tag leyfir að bæta við iframe með kynningu á doc. Þessi kynning er í raun bara einfalt HTML-skrá með handritamerki sem flytur inn CSS forritið þitt á hlaupandi tíma.

Skulum opna kynningu buttons-custom.html  :

Og sjáðu hvernig kóðinn lítur út:

<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>

Það eina sem þarf í þessari skrá er handritið, sem ætti að vera það sama fyrir hvaða kynningu sem þú býrð til í þessari app. The hvíla af the kóða er markup með stíll sem þú vilt sýna í kynningu.

Að auki geturðu notað merkið @demo til að sýna einnig kóðann af kóða sem notaður er í henni. Svona:

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

Hver mun framleiða svona:

Lánshæfiseinkunn fer að Stígvél þar sem við smellum kóðann frá.

Nú, áður en þú ferð í banana með þetta, eru nokkrar fleiri dágóður sem þú getur notfært sér af:

• Búa til stílhluta
• Búa til sniðmátahópa

Búa til stílhluta

Til að búa til stílhluta geturðu notað merkið @styles . Þetta merki er sætt vegna þess að það gerir þér kleift að brjóta niður stílskjalið þitt í skynsamlegar klumpur sem þú getur talað um og skilið betur.

Til dæmis, í dæmi okkar, höfum við stíll til að skilgreina hnappa almennt, óháð því hvaða merkingu er notuð (annaðhvort a á móti tag). Og þá höfum við skilgreiningar á lit. Með @styles merki sem við getum brætt litarskilgreiningarnar í eigin kafla, ekki aðeins að tala um þau sérstaklega, en að geta tengst beint við þann hluta.

Þetta er hvernig það virkar. Í sömu skrá buttons-custom.less , við erum að fara að bæta við merkinu @styles strax eftir fyrsta stíll stíll og fyrir litabreyturnar. Hér er hvernig það ætti að líta út:

/*** @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;

Það eru nokkrir hlutir til að benda á hér:

• Ég uppfærði fyrstu kynningu til að sýna aðeins hnappategundirnar.
• Ég bætti við nýjum athugasemdareit með því að nota @styles tag. Hér gaf ég það einstakt nafn button-colors og titillinn Button Colors . Ég gaf það líka a @description og bætt við a @demo fyrir það sem aðeins sýnir hnappinn litum.

Og hér er framleiðsla:

Takið eftir að nýju athugasemdarnetið er nú hluti af "Hnappar" skjalinu, sem þú getur einnig nálgast beint með þessum vefslóð: http://localhost: 8080 / styleguide / buttons-colors.html

Ég finn persónulega þessa frábæru gagnlega vegna þess að þú getur bent fólki á tiltekna hluta í stýrihandbókinni, og segir: " Er á x síðu, undir x kafla, þá þarftu að fletta ... og blað, bla, bla ". Í staðinn getur þú veitt bein tengsl við það og lok sögunnar.

Búa til sniðmátahópa

Að auki er einnig hægt að búa til köflum eða hópa í skenkur í stílhandbókinni. Fyrir þetta skaltu opna skrána styles.md , staðsett í markdown Skrá.

Þú munt taka eftir hér nýtt merki sem heitir @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.

Nú skulum brjóta niður aðra línu:

@group

The @group merkið gerir þér kleift að búa til hluta í hliðarstikunni sem birtist undir foreldrahlutanum. Til dæmis munu hóparnir: "Þema" og "Grunnlína" birtast undir foreldrahlutanum "Stíll".

styles.theme

Þetta er einstakt heiti hópsins. Gott starf til að fylgja hér er að nota nafn foreldrahlutans, í þessu tilfelli "Stíll" sem nöfn. Á þennan hátt, ef þú vilt búa til annan hóp með sama nafni, en undir öðru hlutanum, mun nafnið á hópnum vera einstakt.

0

Þetta er röðin þar sem hópurinn ætti að birtast, sem byrjar með 0. Ef engin röð er úthlutað birtist listi yfir hópa í stafrófsröð.

Theme

Þetta er raunverulegt nafn sem mun birtast í skenkurnum, svo þú getur notað mörg orð með bilum og öðrum stafi.

Til að sjá hópa í aðgerð, við skulum bæta við nýjum hópi sem hér segir:

@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.

Að lokum, við skulum bæta við núverandi skjali undir þessari nýju kafla. Fyrir þetta opnaðu skrána forms-custom.less :

Og á línu 3, skipta um styles.base fyrir styles.forms .

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

Þá keyra skjölin og endurnýja vafrann. Þú munt nú sjá "Form Elements" doc undir hópnum "Forms" í hliðarstikunni.

Klára

Vinnuskilyrði Stílleiðbeiningar eru tæki til að búa til samkvæmari og samloðandi UI-hönnun, og þú getur raunverulega nýtt þér þá þegar þú sækir Style Guide Bein þróunaraðferð og skjöl skjalfesta css lifandi stíl fylgja lsg stíl fylgja