Hur man skapar en Living Style Guide

Att använda en livsstilguide (LSG) för att driva utveckling är en övning som blir mycket populär eftersom den har många fördelar, inklusive kod effektivitet och UI-konsistens. Men hur kan du skapa en? Vad ska du inkludera? Och var börjar du ens? I denna handledning kommer jag att dyka in i de nitty-gritty detaljerna om att skapa en levande stil med DocumentCSS .

The Beauty of Living Style Guides

På samma sätt som en standardstylguide ger en levande stilguide en uppsättning standarder för användning och skapande av stilar för en applikation. När det gäller en standardstylguide är syftet att upprätthålla varumärkessamhållighet och förhindra missbruk av grafik och designelement. På samma sätt används LSGs för att upprätthålla konsistens i en applikation och att styra implementeringen. Men det som gör en LSG annorlunda och kraftfullare är att mycket av sin information kommer direkt från källkoden, vilket gör det enkelt och effektivt att reflektera det utvecklande tillståndet för en applikation.

Ännu idag är det tänkt att veta att du kan använda källkoden i din ansökan för att bygga din stilguide.

Om du tittar på exemplen nedan ser du de gemensamma beteckningarna för en LSG är:

• En lista över de element som dokumenteras
• Succinkt dokumentation med kodutdrag och interaktiva användargruppdemonstrationer

Lonely Planet Style Guide

Sales Force Style Guide

Ett annat viktigt inslag i en LSG är att du kan använda en stilguidegenerator för att automatisera processen. En stilguidegenerator kommer att använda din källkod för ansökan för att mata huvuddelen av din LSG-dokumentation och titta på eventuella ändringar som görs i din kod, och se till att du uppdaterar din stilvägledningsdokumentation när din ansökan ändras.

Style Guide Generators

Det finns många smaker att välja mellan, beroende på vilket kodsprog du vill dokumentera eller din projektinställning. Här är några ställen att leta efter alternativ:

• En in-djup överblick över Living Style Guide Tools , Robert Haritonov, Smashing Magazine
• Översikt över Pattern Library Generators , David Hund, GitHub
• Style Guide Generator Roundup , Susan Robertson, en lista utöver
• Style Guide Tools , Webbplatsens stilguide

För denna handledning kommer jag att visa dig hur du kan använda DocumentCSS för att skapa din LSG. Detta verktyg som skapats av Bitovi är öppen källkod och kan användas i alla projekt för att dokumentera CSS (förprocessorer som Less och SASS stöds också). Om du är intresserad av att dokumentera Javascript och andra språk kan du enkelt göra det med DocumentCSS, eftersom det här verktyget är en delmängd av DocumentJS. Jag kommer inte att täcka den delen i denna handledning, men det är bra att komma ihåg.

Planera din stilguide

Innan du dyker på att skapa ditt LSG planerar det första steget vad som kommer att vara i det. Som en bra webbplats är en välstrukturerad informationsarkitektur (IE) nyckeln.

Så låt oss börja med att använda följande uppsättning mönster av vår app som heter "Vintage Shop" och observera de ihållande elementen i användargränssnittet:

Vintage Shop Mockups

Vid denna punkt rekommenderar jag att du börjar med större grupper av element, till exempel navigering, vagn eller formulär. Till exempel separerar vi vår design i dessa tre grupper: stegindikatorn, minikorgen och produkterna i kundvagnen:

Med dessa större grupper av element kan du börja gå in i mer detalj och identifiera "stilar" som kvarstår. Till exempel finns en konvention för typografi i allmänhet, och mer specifikt för rubrikerna, underrubrikerna och länkarna jämfört med vanlig text. Färgen på knapparna fortsätter också över sidorna.

Om vi ​​sätter allt ihop, låt oss skriva ner dessa grupper med hjälp av ett diagram:

Om du tar en djupare titt på dessa grupper kan du finjustera dem och göra dem till kategorier som du kan använda i din stilguide när det växer. Till exempel:

• "Elements" är en väldigt vag term som kan referera till något HTML-element, så ett bättre namn för denna grupp kan vara "Components" eller "Modules. Dessa är fortfarande brett men är mer specifika för typen av element som skulle täcka.
• "Primär vs sekundär" -knappar kan vara en del av "Baselement", och färgaspekten av den kan gå in i en "Färgpalett" -kategori.

Dessutom kan du tänka på en kategori där du kan inkludera mer generisk information om din stilguide. Ett bra exempel på det skulle vara en "Guides" -sektion där du kan beskriva hur du bidrar till stilguiden eller en "Branding" -sektion där du kan inkludera riktlinjer för ditt varumärke som bör beaktas när du utformar och implementerar din app.

Med detta i åtanke är här vad diagrammet skulle se ut:

Du kan se hur det här diagrammet tar form av en webbplatskarta, vilket är i grund och botten vad du vill använda som en plan när du skapar din levande stilguide.

Dyk nu in i mönstren och skissa upp din egen sajtkarta, inklusive så många kategorier som du tror skulle vara användbar för framtiden. Du kan få idéer från andra stilguider ( styleguides.io/examples är en stor resurs). När du är klar, kolla den här mer omfattande versionen och jämföra.

Skapa sidor i en Living Style Guide

Medan huvuddelen av din LSG-dokumentation kommer från speciella kommentarer som du lägger till i källkoden kan du även skapa fristående sidor där du kan vara värd för andra typer av innehåll som inte är specifika för koden (tänk på konstruktionsprinciper, riktlinjer för tillgänglighet, eller dra förfrågningsriktlinjer). Detta ger dig fördelen av att centralisera din dokumentation på ett ställe: din ansökan levande stil guide.

Du kan nästan tänka på den levande stilguiden som "spelreglerna" för din app. Inne i "reglerna" är all information som behövs för hur man "spelar" spelet: byggstenarna och reglerna för att skapa och bygga nya block. Inkluderar hur andra medlemmar av ditt team kan bidra till det och hjälpa till att upprätthålla det som ett levande dokument.

_{Yas! Tro på det. Du kan få alla dina dokument konsoliderade på ett enda ställe!}

Med detta i åtanke, låt oss börja med att installera den provprogram som vi ska använda för denna handledning.

Installera provprogrammet

Installationsprocessen har 3 steg:

1. Installera nod

Först, se till att du har Nod installerad. Du behöver minst version 6.

2. Installera appen

Hämta sedan den här zip-filen: sgdd-tutorial.zip till skrivbordet och pakka ut det . Detta är viktigt eftersom en annan plats skulle bryta installationskommandon.

Öppna sedan terminalen och ange följande kommando:

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

Det tar några sekunder att installera appen och dess beroenden.

3. Kör appen

När installationen är klar anger du följande kommandon:

1. npm run develop
2. Ange i en ny flik: npm run document

Nu, låt oss bryta ner det här:

npm run develop

Startar en server där du kan se din app visas på: http://localhost: 8080. Du kommer att se i terminalen:

Och i webbläsaren:

npm run document

Genererar den levande stilguiden på http://localhost: 8080 / skrivregler. Du kan lägga till flaggan -- -w till det här kommandot för att titta på ändringar i din kod och sedan generera en uppdatering i den levande stilguiden, så här:

npm run document -- -w

Byter till webbläsaren bör du se:

Den genererade livsstilguiden använder DocumentCSS , så låt oss ta en titt på hur det fungerar.

Hur fungerar DocumentCSS?

DocumentCSS är en statisk webbplatsgenerator. Det betyder att det letar efter speciellt formaterade kommentarer i din kod och skapar en statisk webbplats. Denna webbplats kallas "statisk" eftersom den förblir oförändrad tills ett kommando (i det här fallet documentjs ) körs igen. Detta arbetsflöde fungerar bra för att generera en levande stilguide eftersom ändringar i dina stylesheets också ändras till den statiska webbplatsen Living Style Guide.

För att bygga en levande stilguide gör DocumentCSS följande:

• Läser igenom filer som anges i dess konfiguration (för den här handledningen kommer den att ses på .less och .md filer)
• Letar efter kommentarer som använder särskilda "taggar" (som @page , @stylesheet eller @styles .
• Genererar html-filer och ansluter dem till att bygga webbplatsen.

Med detta i åtanke ska vi hoppa in med DocumentCSS för att skapa en ny sida i LSG.

Skapa en sida

Börja först öppna provprogrammet i din kodredigerare. Du bör se följande filstruktur:

Borra ner i src och hitta base/markdown . Här hittar du sidor som redan finns i stilguiden. Skapa en ny markdown-fil och namnge den "om" (med tillägget .md ). Din filstruktur ska nu se ut så här:

Inne i den här nya filen lägger du till taggen @page följt av två strängar:

@page about about

Låt oss nu bryta ner det här:

@page

Taggen @page förklarar filen som en sida och berättar DocumentCSS att informationen i den här filen ska visas som en sida i stilguiden. Detta tjänar till att skilja det från stylesheets, javascript eller andra typer av filer i din dokumentation.

about

Detta är det unika namnet på sidan och används som referens till andra taggar. Så håll den kort, liten och enkel eftersom den kommer att användas som webbadressen för sidan. För vårt exempel kommer webbadressen till vår nya sida att vara: http://localhost: 8080 / skrivregler / about.html

About

Detta är titeln på sidan som kommer att användas för visning i den genererade webbplatsen. Här kan du använda flera ord med mellanslag eller andra tecken.

Om du vill visa den nyskapade sidan kör dokumentis i terminalen igen (om du inte har det att titta på för ändringar) och gå till http://localhost: 8080 / skrivregler / about.html för att se den nya sidan.

Nästa steg är att lägga till din sida i navigeringen. För detta lägg till en andra rad till din fil enligt följande:

@page about About@parent index

Taggen @parent tillåter att ange en förälder för ditt dokument. I det här fallet vill vi att sidan "Om" visas under hemavsnittet. Nu kan du omdirigera dokumenten och se sidan visas under länken "Välkommen":

Och om du klickar på länken "Välkommen" kan du komma till startsidan:

Nu är det bra att lägga till innehåll på den här sidan med markdown eller html. För att avsluta träningen lägger vi till följande dummyinnehåll:

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

Och här är utsignalen:

Dokumentation av ett stilark i en Living Style Guide

Hjärtat med att skapa en LSG är möjligheten att sätta din dokumentation rätt där den tillhör: i källkoden. Chansen är att du redan dokumenterar din kod, vilket är ett utmärkt tillfälle att ta det till nästa nivå genom att använda en stilguidegenerator som kan göra dessa kommentarer till en organiserad webbplats, så att andra (och dig själv från framtiden) vet varför och vad har gjorts i koden.

Du själv från framtiden efter att ha läst de dokument du skrev tidigare.

Dokumentation av ett stilark

Dokumentation av ett stylesheet följer ett liknande mönster till dokumentera en sida , men i så fall kommer dokumentationen att gå in i en kommentar, precis bredvid koden (det är skönheten!).

För att komma igång öppna stilarket: buttons-custom.less .

Inne i den här filen och inuti ett kommentarblock lägger du till taggen @stylesheet följt av två strängar:

/**@stylesheet buttons.less Buttons*/

Observera att dokumentationskommentaren måste börja med /** för parsern (i detta fall JSDoc ) att erkänna det.

Låt oss nu bryta ner det här:

@stylesheet

Taggen @stylesheet förklarar filen som ett stilark och berättar DocumentCSS att informationen i den här filen ska visas en sådan i stilguiden. Detta tjänar till att skilja det från andra typer av dokument, t.ex. sidor, komponenter och modeller, bland annat ( Läs här om hela listan med dokumenttyper ).

buttons.less

Detta är det unika namnet för stilarket och används som en hänvisning till andra taggar. Medan du kan använda vilken typ av namn som helst, rekommenderar jag att du använder namnet på formatarkfilen, eftersom det här hjälper till att hitta filen när du refererar till dokumentationen. Tänk på att detta kommer att påverka URL-adressen till ditt dokument. För detta exempel kommer URL: http://localhost: 8080 / skrivregler / buttons.less.html

Buttons

Liknande skapa en sida , det här är titeln på stilarket som ska användas för visning i den genererade webbplatsen. Här kan du använda flera ord med mellanslag eller andra tecken.

Om du vill visa den nyskapade sidan kör följande kommando om du inte har det att titta på för ändringar):

documentjs

Och sedan gå till http://localhost: 8080 / skrivregler / buttons.less.html för att se den nya sidan.

Nu lägger vi till det här nya dokumentet till vår navigering. För detta följer vi samma konvention som vi använde när vi skapade sidan med hjälp av @parent märka:

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

Observera att vi i detta fall har lagt till .base att ange denna sida ska visas under gruppen "Baseline" som visas i sidofältet (du kan även skapa grupper i din subnav! Vi kommer att gräva in det på en liten bit).

Återställningen av dokumenten och uppdatering av sidan ska se ut så här:

Nu för den köttiga delen! Med vår sida på plats kan vi göra några saker:

• Vi kan lägga till en övergripande beskrivning för doc
• Vi kan lägga till alla slags innehåll med både markdown eller vanlig HTML
• Och bäst av allt kan vi lägga till demos för vår kod?

Låt oss lägga till en snabb beskrivning och en demo för våra knappar 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 docs, och?:

Som du kan se @iframe taggen tillåter att lägga till en iframe med en demo till ditt dokument. Denna demo är egentligen bara en enkel html-fil med en skriptikett som importerar CSS till din app vid körning.

Låt oss öppna demoen buttons-custom.html  :

Och se hur koden ser ut:

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

Det enda som krävs i den här filen är skriptet, vilket borde vara detsamma för alla demo som du skapar i den här appen. Resten av koden är markeringen med de stilar som du vill visa i demo.

Dessutom kan du använda taggen @demo för att även visa kodens kod som används i den. Så här:

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

Vilket kommer att mata ut så här:

Demokredit går till Bootstrap Docs där vi snapar koden från.

Nu, innan du går bananer med det här, finns det ett par mer godsaker som du kan dra nytta av:

• Skapa stilavsnitt
• Skapa stilarkrupper

Skapa stilavsnitt

För att skapa en stil sektion kan du använda taggen @styles . Den här taggen är söt eftersom den låter dig bryta ner ditt stilarkdokument till förnuftiga bitar som du kan prata om och förstå bättre.

Till exempel, i vårt exempel har vi stilar för att definiera knappar i allmänhet, oberoende av markeringen som används (antingen a mot märka). Och då har vi definitioner av färg. Med @styles tagg kan vi bryta färgdefinitionerna i sin egen sektion, inte bara för att prata om dem separat, men för att kunna hyperlänk till den sektionen direkt.

Så här fungerar det. I samma fil buttons-custom.less , vi ska lägga till taggen @styles strax efter det första blocket av stilar och före färgvariablerna. Så här ska det se ut:

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

Det finns ett par saker att peka på här:

• Jag uppdaterade den första demoen för att bara visa knapptyperna.
• Jag lade till ett nytt kommentarblock med hjälp av @styles märka. Här gav jag det ett unikt namn button-colors och titeln på Button Colors . Jag gav också den en @description och tillade a @demo för det som bara visar knappfärgerna.

Och här är utsignalen:

Observera att det nya kommandoblocket nu är en sektion inom "Knappar" doc, som du också kan komma åt direkt med den här url: http://localhost: 8080 / styleguide / buttons-colors.html

Jag tycker personligen att detta är super användbart eftersom du kan peka människor på ett specifikt avsnitt i stilguiden, och säger: " finns på x-sida, under x-sektionen, då behöver du bläddra ... och bla, bla, bla ". I stället kan du ge en direkt länk till den och slutet av historien.

Skapa stilarkrupper

Dessutom kan du även skapa sektioner eller grupper i sidostilen i stilguiden. För detta, öppna filen styles.md , belägen i markdown katalogen.

Du kommer att märka här en ny tagg som heter @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.

Låt oss nu bryta ner den andra raden:

@group

De @group tagg kan du skapa en sektion i sidofältet som visas under överordnad sektion. Till exempel kommer grupperna: "Tema" och "Baslinje" att visas under överordnade avsnittet "Stilar".

styles.theme

Detta är det unika namnet för gruppen. En bra övning att följa här är att använda namnet på föräldraavsnittet, i det här fallet "Styles" som namnrymd. På så sätt, om du vill skapa en annan grupp med samma namn, men under ett annat avsnitt, kommer gruppen att vara unik.

0

Detta är den ordning i vilken gruppen ska visas, vilken börjar med 0. Om ingen order har tilldelats visas listan med grupper i alfabetisk ordning.

Theme

Det här är det faktiska namnet som visas i sidofältet, så du kan använda flera ord med mellanslag och andra tecken.

För att se grupper i åtgärd, låt oss lägga till en ny grupp enligt följande:

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

Till sist lägger vi till ett befintligt dokument under den här nya sektionen. För att öppna filen forms-custom.less :

Och på rad 3, ersätt styles.base för styles.forms .

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

Kör sedan docsna och uppdatera webbläsaren. Du kommer nu att se "Form Elements" doc under gruppen "Forms" i sidofältet.

Sammanfatta

Living Style Guides är ett verktyg för att skapa mer konsekventa och sammanhängande användargränssnitt, och du kan verkligen dra nytta av dem när du tillämpar Style Guide Driven utvecklingsmetod och när man utformar på ett modulärt sätt .

Du bygger byggnadsledare på denna punkt!

dokumentation dokumentera css levande stil guide lsg stil guider