Sådan opretter du en Living Style Guide

Brug af en levende stil guide (LSG) til at drive udvikling er en praksis, der vinder meget popularitet, fordi det har mange fordele, herunder kode effektivitet og UI konsistens. Men hvordan kan du oprette en? Hvad skal du medtage? Og hvor starter du selv? I denne tutorial vil jeg dykke i de nitty-gritty detaljer om at skabe en levende stil bruger DocumentCSS .

The Beauty of Living Style Guides

I lighed med en standard stil guide giver en levende stil guide et sæt standarder for brug og oprettelse af stilarter til en applikation. I tilfælde af en standard stil guide er formålet at opretholde brand sammenhængskraft og forhindre misbrug af grafik og designelementer. På samme måde bruges LSG'er til at opretholde sammenhæng i en applikation og at styre deres implementering. Men hvad der gør en LSG anderledes og mere kraftfuld er, at meget af sin information kommer lige fra kildekoden, hvilket gør det nemt og effektivt at reflektere udviklingen af ​​en applikation.

Selv i dag er det sjovt at vide, at du kan bruge kildekoden til din ansøgning til at opbygge din stilguide.

Hvis du ser på eksemplerne nedenfor, vil du se de fælles betegnelser for en LSG er:

• En liste over de elementer, der er dokumenteret
• Succinct dokumentation med kodestykker og interaktive UI demonstrationer

Lonely Planet Style Guide

Sales Force Style Guide

Et andet vigtigt element i en LSG er, at du kan bruge en style guide generator til at automatisere processen. En stilguidegenerator vil bruge din kildekode til at matche hovedparten af ​​din LSG-dokumentation og se efter eventuelle ændringer i din kode, og sørg for at opdatere din stilvejledningsdokumentation, når din ansøgning ændres.

Style Guide Generatorer

Der er mange smag at vælge imellem afhængigt af det kodesprog, du vil dokumentere eller din projektopsætning. Her er nogle steder at søge efter muligheder:

• En dybdeoversigt over Living Style Guide Tools , Robert Haritonov, Smashing Magazine
• Oversigt over Mønsterbibliotek Generatorer , David Hund, GitHub
• Style Guide Generator Roundup , Susan Robertson, en liste fra hinanden
• Style Guide Værktøjer , Website Style Guide Ressourcer

Til denne øvelse vil jeg vise dig, hvordan du kan bruge DocumentCSS til at oprette din LSG. Dette værktøj skabt af Bitovi er open source og kan bruges i ethvert projekt til at dokumentere CSS (præprocessorer som Mindre og SASS understøttes også). Hvis du er interesseret i at dokumentere Javascript og andre sprog, kan du nemt gøre det med DocumentCSS, da dette værktøj er en delmængde af DocumentJS. Jeg vil ikke dække den del i denne tutorial, men det er godt at huske på.

Planlægning af din stilguide

Før du dykker ind i at oprette din LSG, planlægger det første skridt, hvad der vil være i det. Ligesom ethvert godt websted er en velstruktureret informationsarkitektur (IE) nøglen.

Så lad os komme i gang ved at bruge følgende sæt design af vores sample app kaldet "Vintage Shop" og observere de vedholdende elementer i brugergrænsefladen:

Vintage Shop Mockups

På dette tidspunkt anbefaler jeg at starte med større grupper af elementer, såsom navigationen, vognen eller formularerne. For eksempel adskiller vi vores design i disse tre grupper: trinindikatoren, minibaren og produkterne i kurven:

Med disse større grupper af elementer kan du begynde at gå i detaljer og identificere de "stilarter", der vedvarer. For eksempel er der en konvention for typografien generelt og mere specifikt for overskrifterne, underpositionerne og linkene versus almindelig tekst. Farven på knapperne fortsætter også på tværs af siderne.

Sæt det hele sammen, lad os skrive ned disse grupper ved hjælp af et diagram:

Hvis du tager et dybere kig ind i disse grupper, kan du finjustere dem og gøre dem til kategorier, som du kan bruge i din stilguide, da den vokser. For eksempel:

• "Elements" er en meget vag term, der kan henvise til ethvert HTML element, så et bedre navn til denne gruppe kan være "Components" eller "Modules. Disse er stadig brede udtryk, men er mere specifikke for typen af ​​elementer, der dækker.
• Knapper "Primary vs Secondary" kunne være en del af "Base Elements", og farveaspektet af det kunne gå ind i en "Color Palette" kategori.

Derudover kan du tænke på en kategori, hvor du kan inkludere mere generiske oplysninger om din stilguide. Et godt eksempel på dette ville være en "Guides" sektion, hvor du kunne beskrive, hvordan du bidrager til stilguiden eller en "Branding" sektion, hvor du kan inkludere retningslinjer for dit brand, der skal holdes i tankerne, når du designer og implementerer din app.

Med dette i tankerne, her er hvad diagrammet ville se ud:

Du kan se, hvordan dette diagram har form af et sitemap, hvilket grundlæggende er det, du vil bruge som en plan, når du opretter din levende stilguide.

Dyk nu ind i designene og skits dit eget webstedskort, herunder så mange kategorier som du tror, ​​ville være nyttigt for fremtiden. Du kan få ideer fra andre stilguider ( styleguides.io/examples er en stor ressource). Når du er færdig, skal du tjekke denne mere omfattende version og sammenligne.

Oprettelse af sider i en levende stilguide

Mens hovedparten af ​​din LSG-dokumentation kommer fra særlige kommentarer, som du tilføjer til kildekoden, kan du også oprette frie sider, hvor du kan være vært for andre typer indhold, der ikke er specifikke for koden (tænk på designprincipper, retningslinjer for tilgængelighed, eller trække anmodning retningslinjer). Dette giver dig den fordel at centralisere din dokumentation på ét sted: din ansøgning levende stil guide.

Du kan næsten tænke på den levende stilguide som "spilreglerne" for din app. Inde i "reglerne" er al den information, der er nødvendig for at "spille" spillet: Byggestenene og reglerne for at skabe og lave nye blokke. Herunder hvordan andre medlemmer af dit team kan bidrage til det og hjælpe med at opretholde det som et levende dokument.

_{Yas! Tro på det. Du kan få alle dine dokumenter konsolideret på et enkelt sted!}

Med dette i tankerne, lad os begynde med at installere den prøveapplikation, som vi vil bruge til denne vejledning.

Installation af prøveapplikationen

Installationsprocessen har 3 trin:

1. Installation af knudepunkt

Først skal du sørge for at have Node installeret. Du skal mindst bruge version 6.

2. Installation af appen

Dernæst download denne zip-fil: sgdd-tutorial.zip til dit skrivebord og pakke det ud . Dette er vigtigt, da en anden placering ville bryde installeringskommandoerne.

Åbn derefter terminalen og indtast følgende kommando:

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

Det tager nogle sekunder at installere appen og dens afhængigheder.

3. Kører appen

Når installationen er færdig, skal du indtaste følgende kommandoer:

1. npm run develop
2. Indtast i en ny fane: npm run document

Lad os nu bryde det ned:

npm run develop

Starter en server, hvor du kan se din app køre på: http://localhost: 8080. Du vil se i terminalen:

Og i browseren:

npm run document

Genererer levende stil guide på http://localhost: 8080 / styleguide. Du kan tilføje flag -- -w til denne kommando for at se efter ændringer i din kode og derefter generere en opdatering i live style guide, som denne:

npm run document -- -w

Skift til browser skal du se:

Den genererede levende stil guide bruger DocumentCSS , så lad os se på hvordan dette virker.

Hvordan virker DocumentCSS?

DocumentCSS er en statisk site generator. Det betyder, at det søger specielt formaterede kommentarer i din kode og opretter en statisk hjemmeside. Dette websted kaldes "statisk", fordi det forbliver uændret, indtil en kommando (i dette tilfælde documentjs ) køres igen. Denne workflow fungerer godt for at generere en levende stilguide, da ændringer i dine stylesheets også ændres til Living Style Guide statisk side.

For at opbygge en levende stil guide, gør DocumentCSS følgende:

• Læser gennem filer specificeret i sin konfiguration (for denne tutorial vil det se på .less og .md filer)
• Leder efter kommentarer, der bruger specielle "tags" (som @page , @stylesheet eller @styles .
• Genererer html-filer og forbinder dem med at opbygge webstedet.

Med dette i tankerne skal vi hoppe ind i at bruge DocumentCSS til at oprette en ny side i LSG.

Oprettelse af en side

For at begynde skal du først åbne prøveapplikationen i din kodeditor. Du skal se følgende filstruktur:

Bor ned i src, og find base/markdown . Her finder du sider, der allerede findes i stilguiden. Opret en ny markdown-fil og navngiv den "om" (med udvidelsen .md ). Din filstruktur skal nu se sådan ud:

Inde i denne nye fil, tilføj tagget @page efterfulgt af to strenge:

@page about about

Lad os nu bryde det ned:

@page

Taggen @page erklærer filen som en side og fortæller DocumentCSS, at oplysningerne i denne fil skal vises som en side i stilguiden. Dette tjener til at differentiere det fra stylesheets, javascript eller andre typer filer i din dokumentation.

about

Dette er det unikke navn på siden og bruges som en henvisning til andre tags. Så hold det kort, små og små, da det bliver brugt som webadressen til siden. For vores eksempel vil url til vores nye side være: http://localhost: 8080 / styleguide / about.html

About

Dette er titlen på den side, der vil blive brugt til visning i det genererede websted. Her kan du bruge flere ord med mellemrum eller andre tegn.

Hvis du vil se den nyoprettede side, skal du køre documentjs i terminalen igen (medmindre du har det til at se efter ændringer), og derefter gå til http://localhost: 8080 / styleguide / about.html for at se den nye side.

Det næste skridt er at tilføje din side til navigationen. For dette tilføj en anden linje til din fil som følger:

@page about About@parent index

Taggen @parent giver mulighed for at angive en forælder for dit dokument. I dette tilfælde ønsker vi at "Om" -siden skal vises under hjemmet. Nu kan du genoprette docs og se siden vises under linket "Velkommen":

Og hvis du klikker på linket "Velkommen", kan du få adgang til startsiden:

Nu er vi gode til at tilføje indhold til denne side ved hjælp af markdown eller html. For at afslutte øvelsen, lad os tilføje følgende dummy indhold:

@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 her er output:

Dokumentere et stylesheet i en Living Style Guide

Hjertet ved at oprette en LSG er evnen til at sætte din dokumentation lige, hvor den tilhører: i kildekoden. Chancerne er, at du allerede dokumenterer din kode, hvilket er en fantastisk mulighed for at tage det til næste niveau ved hjælp af en stilguidegenerator, der kan gøre disse kommentarer til et organiseret websted, så andre (og dig selv fra fremtiden) ved hvorfor og hvad er der sket i koden

Selv fra fremtiden efter at have læst de dokumenter, du skrev i fortiden.

Dokumentation af et stylesheet

Dokumentation af et stylesheet følger et lignende mønster til dokumentere en side , men i dette tilfælde vil dokumentationen gå ind i en kommentar lige ved siden af ​​koden (det er skønheden!).

For at komme i gang åbner stilarket: buttons-custom.less .

Inde i denne fil og inde i en kommentarblok skal du tilføje tagget @stylesheet efterfulgt af to strenge:

/**@stylesheet buttons.less Buttons*/

Bemærk, at dokumentationskommentaren skal begynde med /** for parseren (i dette tilfælde JSDoc ) at anerkende det.

Lad os nu bryde det ned:

@stylesheet

Taggen @stylesheet erklærer filen som stilark og fortæller DocumentCSS at oplysningerne i denne fil skal vises en sådan i stilguiden. Dette tjener til at differentiere det fra andre typer dokumenter, f.eks. Sider, komponenter og modeller, blandt andet ( læs her om den fulde liste over dokumenttyper ).

buttons.less

Dette er det unikke navn for stilarket og bruges som reference til andre tags. Mens du kan bruge en hvilken som helst type navn, anbefaler jeg at bruge navnet på stylesheet-filen, da dette vil hjælpe med at finde filen, når der henvises til dokumentationen. Husk på, at dette vil påvirke webadressen til dit dokument. For dette eksempel vil url være: http://localhost: 8080 / styleguide / buttons.less.html

Buttons

Svarende til oprettelse af en side , dette er titlen på stilarket, der vil blive brugt til visning i det genererede websted. Her kan du bruge flere ord med mellemrum eller andre tegn.

Hvis du vil se den nyoprettede side, skal du køre følgende kommando, medmindre du har det til at se efter ændringer):

documentjs

Og så gå til http://localhost: 8080 / styleguide / buttons.less.html for at se den nye side.

Lad os nu tilføje dette nye dokument til vores navigation. Til dette følger vi den samme konvention, som vi brugte, da vi oprettede siden ved hjælp af @parent tag:

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

Bemærk at i dette tilfælde har vi tilføjet .base at angive denne side skal vises under gruppen "Baseline" vist i sidebjælken (du kan også oprette grupper i din undernavn! Vi vil grave ind i det i en lille smule).

Genudførelse af docs og forfriskning af siden skal se sådan ud:

Nu for den kødfulde del! Med vores side på plads kan vi lave et par ting:

• Vi kan tilføje en samlet beskrivelse af dokumentet
• Vi kan tilføje alle slags indhold ved hjælp af både markdown eller almindelig HTML
• Og bedst af alt kan vi tilføje demoer til vores kode?

Lad os tilføje en hurtig beskrivelse og en demo til vores knapper 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, og?:

Som du kan se @iframe tag giver mulighed for at tilføje en iframe med en demo til din doc. Denne demo er virkelig bare en simpel html-fil med et script-tag, der importerer CSS til din app på kørselstidspunktet.

Lad os åbne demoen buttons-custom.html  :

Og se hvordan koden ser ud:

<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 eneste, der kræves i denne fil, er scriptet, som skal være det samme for enhver demo, du opretter i denne app. Resten af ​​koden er markeringen med de stilarter, du vil vise i demoen.

Derudover kan du bruge tagget @demo at også vise kodestykket der bruges i det. Sådan her:

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

Hvilket vil udgive som følger:

Demoer kredit går til Bootstrap Docs hvor vi snap koden fra.

Nu, før du går bananer med dette, er der et par flere godbidder, som du kan drage fordel af:

• Oprettelse af stilafsnit
• Oprettelse af stilarkgrupper

Oprettelse af stilafsnit

For at oprette en stil sektion kan du bruge tagget @styles . Dette tag er sødt, fordi det giver dig mulighed for at nedbryde dit stylesheet-dokument til fornuftige klumper, som du kan snakke om og forstå bedre.

For eksempel har vi i vores eksempel stilarter til at definere knapper generelt, uanset hvilken markering der bruges (enten a vs tag). Og så har vi definitioner af farve. Med @styles tag vi kan bryde farvedefinitionerne ind i deres eget afsnit, ikke kun for at tale om dem særskilt, men for at kunne hyperlink direkte til det pågældende afsnit.

Sådan virker det. I den samme fil buttons-custom.less , vi skal tilføje tagget @styles lige efter den første blok af stilarter og før farvevariablerne. Sådan ser det ud:

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

Der er et par ting at pege på her:

• Jeg opdaterede den første demo for kun at vise knappetyperne.
• Jeg tilføjede en ny kommentarblok ved hjælp af @styles tag. Her gav jeg det et unikt navn button-colors og titlen på Button Colors . Jeg gav det også en @description og tilføjede a @demo for det der kun viser knappens farver.

Og her er output:

Bemærk, at den nye kommentarblok nu er en sektion inden for "Knapper" doc, som du også kan få direkte adgang til ved hjælp af denne url: http://localhost: 8080 / styleguide / buttons-colors.html

Jeg finder personligt dette super nyttigt, fordi du kan pege folk til et bestemt afsnit i stilguiden, og siger: " er på x side under x afsnit, så skal du rulle ... og bla, bla, bla ". I stedet kan du give et direkte link til det og slutningen af ​​historien.

Oprettelse af stilarkgrupper

Derudover kan du også oprette afsnit eller grupper i sidelinjen i stilguiden. Til dette skal du åbne filen styles.md , placeret i markdown vejviser.

Her vil du se et nyt mærke kaldet @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.

Lad os nu bryde ned den anden linje:

@group

Det @group tag giver dig mulighed for at oprette et afsnit i sidefeltet, der vises under overordnet sektion. For eksempel vil grupperne: "Tema" og "Baseline" blive vist under overordnet afsnittet "Styles".

styles.theme

Dette er det unikke navn for gruppen. En god praksis at følge her er at bruge navnet på overordnet sektion, i dette tilfælde "Styles" som navneområde. På denne måde, hvis du vil oprette en anden gruppe med samme navn, men under et andet afsnit, forbliver gruppenes navn unik.

0

Dette er den rækkefølge, hvor gruppen skal vises, som starter med 0. Hvis ingen ordre er tildelt, vises listen over grupper i alfabetisk rækkefølge.

Theme

Dette er det egentlige navn, der vises i sidefeltet, så du kan bruge flere ord med mellemrum og andre tegn.

For at se grupper i aktion, lad os tilføje en ny gruppe som følger:

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

Endelig lad os tilføje et eksisterende dok under dette nye afsnit. For dette åbner filen forms-custom.less :

Og på linje 3 erstattes styles.base til styles.forms .

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

Kør derefter docs og opdatér browseren. Du vil nu se "Form Elements" doc under gruppen "Forms" i sidepanelet.

Wrap Up

Living Style Guides er et værktøj til at skabe mere sammenhængende og sammenhængende brugergrænseflader, og du kan virkelig udnytte dem, når du anvender Style Guide Driven udviklingsmetode og når man designer på en modulær måde .

Du bygger levende stil guider på dette tidspunkt!

På dette tidspunkt, hvis du har fulgt langs, skal du nu have en løbende Living Style Guide og en gennemtænkt plan for at oprette en LSG, som du kan bruge som basis for andre projekter.

[- Oprindeligt

dokumentation dokumentere css levende stil guide LSG stil guider