Hvordan lage en Living Style Guide

Å bruke en levende stilguide (LSG) for å kjøre utvikling er en praksis som får mye popularitet fordi den har mange fordeler, inkludert kodeeffektivitet og UI-konsistens. Men hvordan kan du lage en? Hva bør du inkludere? Og hvor starter du selv? I denne opplæringen vil jeg dype inn i de nitty-gritty detaljene om å skape en levende stil med DocumentCSS .

The Beauty of Living Style Guides

I likhet med en standard stilguide, gir en levende stilguide et sett med standarder for bruk og utforming av stiler for en applikasjon. I tilfelle av en standard stilguide, er formålet å opprettholde merkevarekonsistens og forhindre misbruk av grafikk og designelementer. På samme måte brukes LSGs for å opprettholde konsistens i et program og å veilede implementeringen. Men det som gjør en LSG forskjellig og kraftigere, er at mye av informasjonen kommer rett fra kildekoden, noe som gjør det enkelt og effektivt å reflektere utviklingsstatusen til et program.

Selv i dag er det tankene som blåser for å lære at du kan bruke kildekoden til søknaden din for å bygge din stilguide.

Hvis du ser på eksemplene nedenfor, vil du se de felles betegnelsene for en LSG er:

• En liste over elementene som er dokumentert
• Suksessdokumentasjon med kodestykker og interaktive UI-demonstrasjoner

Lonely Planet Style Guide

Sales Force Style Guide

Et annet viktig element i en LSG er at du kan bruke en stilguide generator for å automatisere prosessen. En stilguide-generator vil bruke kildekode for søknad til å mate hoveddelen av LSG-dokumentasjonen og se etter eventuelle endringer som er gjort i koden din, og sørg for at du oppdaterer dokumentstyringsdokumentasjonen når søknaden endres.

Style Guide Generators

Det er mange smaker å velge mellom, avhengig av kodespråket du vil dokumentere eller prosjektoppsettet. Her er noen steder å lete etter alternativer:

• En In-Depth Oversikt over Living Style Guide Tools , Robert Haritonov, Smashing Magazine
• Oversikt over Mønsterbibliotek Generatorer , David Hund, GitHub
• Style Guide Generator Roundup , Susan Robertson, en liste fra hverandre
• Stilguideverktøy , Website Style Guide Resources

For denne opplæringen vil jeg vise deg hvordan du kan bruke DocumentCSS til å lage LSG. Dette verktøyet opprettet av Bitovi er åpen kildekode og kan brukes i ethvert prosjekt for å dokumentere CSS (forprosessorer som Mindre og SASS støttes også). Hvis du er interessert i å dokumentere Javascript og andre språk, kan du enkelt gjøre det med DocumentCSS, da dette verktøyet er en delmengde av DocumentJS. Jeg vil ikke dekke den delen i denne opplæringen, men det er godt å huske på.

Planlegg din stilguide

Før du dykker inn i å lage ditt LSG, er det første trinnet som planlegger hva som skal være i det. Som en god nettside er en velstrukturert informasjonarkitektur (IE) nøkkelen.

Så la oss begynne med å bruke følgende sett med design av vår prøveapp, kalt "Vintage Shop", og observere de vedvarende elementene i brukergrensesnittet:

Vintage Shop Mockups

På dette punktet anbefaler jeg at du starter med større grupper av elementer, for eksempel navigasjonen, handlekurven eller skjemaene. For eksempel skiller vi vårt design inn i disse tre gruppene: trinnindikatoren, minibaren og produktene i handlekurven:

Med disse større gruppene av elementer kan du begynne å gå inn i mer detalj og identifisere "stiler" som vedvarer. For eksempel er det en konvensjon for typografien generelt, og mer spesifikt for overskriftene, underrubrikkene og koblingene mot vanlig tekst. Fargene på knappene fortsetter også over sidene.

Sett alt sammen, la oss skrive ned disse gruppene ved hjelp av et diagram:

Hvis du tar et dypere innblikk i disse gruppene, kan du finjustere dem og gjøre dem til kategorier som du kan bruke i din stilguide når det vokser. For eksempel:

• "Elements" er en veldig vag term som kan referere til et hvilket som helst HTML element, så et bedre navn for denne gruppen kan være "Components" eller "Modules. Disse er fortsatt brede vilkår, men er mer spesifikke i arten av typen elementer som vil dekke.
• Knapper "Primary vs Secondary" kan være en del av "Base Elements", og fargepartiet av det kan gå inn i en "Color Palette" kategori.

I tillegg kan du tenke på en kategori der du kan inkludere mer generisk informasjon om din stilguide. Et godt eksempel på det ville være en "Guides" -seksjon der du kunne beskrive hvordan du bidrar til stilguiden eller en «Branding» -seksjon der du kan inkludere retningslinjer for merkevaren din som bør holdes i bakhodet når du utformer og implementerer appen din.

Med dette i tankene, her er hva diagrammet vil se ut:

Du kan se hvordan dette diagrammet har formen av et nettstedskart, som egentlig er hva du vil bruke som en plan når du oppretter din levende stilguide.

Nå dykk inn i designene og skisser opp ditt eget nettstedskart, inkludert så mange kategorier som du tror, ​​vil være nyttig for fremtiden. Du kan få ideer fra andre stilguider ( styleguides.io/examples er en stor ressurs). Når du er ferdig, sjekk denne mer omfattende versjonen og sammenlign.

Opprette sider i en Living Style Guide

Mens hovedparten av LSG-dokumentasjonen kommer fra spesielle kommentarer som du legger til kildekoden, kan du også opprette frittstående sider der du kan være vert for andre typer innhold som ikke er spesifikke for koden (tenk på designprinsipper, retningslinjer for tilgjengelighet, eller trekk forespørselsretningslinjer). Dette gir deg fordelen av å sentralisere dokumentasjonen på ett sted: Din søknadsveiledningsguide.

Du kan nesten tenke på levende stilguide som "spillregler" for appen din. Inne i "reglene" er all den informasjonen som trengs for å "spille" spillet: Byggeblokkene og reglene for å lage og lage nye blokker. Inkludert hvordan andre medlemmer av teamet ditt kan bidra til det og bidra til å opprettholde det som et levende dokument.

_{Yas! Tro det. Du kan ha alle dine dokumenter konsolidert på ett sted!}

Med dette i tankene, la oss begynne med å installere prøveapplikasjonen som vi skal bruke for denne opplæringen.

Installere prøveapplikasjonen

Installasjonsprosessen har tre trinn:

1. Installere knutepunkt

Først må du sørge for at du har det node installert. Du trenger minst versjon 6.

2. Installere appen

Last ned denne zip-filen: sgdd-tutorial.zip til skrivebordet og pakke det ut . Dette er viktig fordi en annen plassering ville ødelegge installasjonskommandoene.

Åpne deretter terminalen og skriv inn følgende kommando:

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

Det tar noen sekunder å installere appen og dens avhengigheter.

3. Kjører programmet

Når installasjonen er ferdig, skriv inn følgende kommandoer:

1. npm run develop
2. Skriv inn en ny kategori: npm run document

La oss nå bryte ned dette:

npm run develop

Starter en server hvor du kan se at appen din kjører på: http://localhost: 8080. Du vil se i terminalen:

Og i nettleseren:

npm run document

Genererer levestilen guide på http://localhost: 8080 / stilmanual. Du kan legge til flagget -- -w til denne kommandoen for å se etter endringer i koden din og deretter generere en oppdatering i den levende stilguiden, slik som dette:

npm run document -- -w

Bytter til nettleseren bør du se:

Den genererte levende stilguiden bruker DocumentCSS , så la oss ta en titt på hvordan dette virker.

Hvordan fungerer DocumentCSS?

DocumentCSS er en statisk nettsted generator. Dette betyr at det ser etter spesielle formaterte kommentarer i koden din og lager et statisk nettsted. Dette nettstedet kalles "statisk" fordi det forblir uendret til en kommando (i dette tilfellet documentjs ) kjøres igjen. Denne arbeidsflyten fungerer bra for å generere en levende stilveiledning, da endringer i stilarkene dine også endres i statisk stil for Living Style Guide.

For å bygge en levende stilguide, gjør DocumentCSS følgende:

• Leser gjennom filer angitt i konfigurasjonen (for denne opplæringen vil den se på .less og .md filer)
• Ser etter kommentarer som bruker spesielle "tags" (som @page , @stylesheet eller @styles .
• Genererer html-filer og kobler dem til å bygge nettstedet.

Med dette i tankene, la oss hoppe inn med DocumentCSS for å lage en ny side i LSG.

Opprette en side

For å begynne, må du først åpne prøveapplikasjonen i kodeditoren din. Du bør se følgende filstruktur:

Drill ned i src, og finn base/markdown . Her finner du sider som allerede finnes i stilguiden. Opprett en ny markdown-fil og navnet "om" (med utvidelsen .md ). Din filstruktur burde nå se slik ut:

Innsiden av denne nye filen, legg til taggen @page etterfulgt av to strenger:

@page about about

La oss nå bryte ned dette:

@page

Merket @page erklærer filen som en side og forteller DocumentCSS at informasjonen i denne filen skal vises som en side i stilguiden. Dette tjener til å skille det fra stilark, javascript eller andre typer filer i dokumentasjonen.

about

Dette er det unike navnet på siden, og brukes som referanse til andre tagger. Så hold den kort, liten og enkel, da den vil bli brukt som URL for siden. For vårt eksempel vil nettadressen til vår nye side være: http://localhost: 8080 / stilmanual / about.html

About

Dette er tittelen på siden som skal brukes til visning i det genererte nettstedet. Her kan du bruke flere ord med mellomrom eller andre tegn.

For å vise den nylig opprettede siden, kjør dokumentis i terminalen igjen (med mindre du har den på å se etter endringer), og deretter gå til http://localhost: 8080 / stilmanual / about.html for å vise den nye siden.

Det neste trinnet er å legge til siden din i navigasjonen. For dette legger du til en andre linje i filen din på følgende måte:

@page about About@parent index

Merket @parent Lar deg spesifisere en forelder for dokumentet ditt. I dette tilfellet ønsker vi at "Om" -siden skal vises under hjemmet. Nå kan du omdanne dokumentene og se siden vises under "Velkommen" -linken:

Og hvis du klikker på "Velkommen" -linken, kan du få tilgang til startsiden:

Nå er det bra å legge til innhold på denne siden ved hjelp av markdown eller html. For å fullføre øvelsen, la oss legge til følgende dummy innhold:

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

Dokumentere et stilark i en Living Style Guide

Hjertet med å lage en LSG er evnen til å sette dokumentasjonen din akkurat der den tilhører: i kildekoden. Sjansen er at du allerede dokumenterer koden din, noe som er en flott mulighet til å ta det til neste nivå ved hjelp av en stilguidegenerator som kan gjøre disse kommentarene til et organisert nettsted, slik at andre (og deg selv fra fremtiden) vet hvorfor og hva har blitt gjort i koden.

Selv fra fremtiden etter å ha lest dokumentene du skrev i fortiden.

Dokumentere et stilark

Dokumentere et stilark følger et lignende mønster til dokumentere en side , men i dette tilfellet vil dokumentasjonen gå inn i en kommentar, rett ved siden av koden (det er skjønnheten!).

For å komme i gang, åpne stilarket: buttons-custom.less .

Innsiden av denne filen og innsiden av en kommentarblokk legger til taggen @stylesheet etterfulgt av to strenger:

/**@stylesheet buttons.less Buttons*/

Merk at dokumentasjonskommentaren må begynne med /** for parseren (i dette tilfellet JSDoc ) å anerkjenne det.

La oss nå bryte ned dette:

@stylesheet

Merket @stylesheet erklærer filen som et stilark og forteller DocumentCSS at informasjonen i denne filen skal vises en slik i stilguiden. Dette tjener til å skille det fra andre typer dokumenter, som sider, komponenter og modeller, blant annet ( Les her om hele listen over dokumenttyper ).

buttons.less

Dette er det unike navnet på stilarket og brukes som referanse til andre tagger. Mens du kan bruke en hvilken som helst type navn, anbefaler jeg at du bruker navnet på stilarkfilen, da dette vil hjelpe til med å finne filen når du refererer til dokumentasjonen. Husk at dette vil påvirke dokumentets URL-adresse. For dette eksempelet vil nettadressen være: http://localhost: 8080 / stilmanual / buttons.less.html

Buttons

Lik opprette en side , dette er tittelen på stilarket som skal brukes til visning i det genererte nettstedet. Her kan du bruke flere ord med mellomrom eller andre tegn.

For å se den nyopprettede siden, kjør følgende kommando, med mindre du har det å se etter endringer):

documentjs

Og så gå til http://localhost: 8080 / stilmanual / buttons.less.html for å vise den nye siden.

La oss nå legge til dette nye dokumentet til vår navigasjon. For dette vil vi følge samme konvensjon vi brukte da vi opprettet siden ved å bruke @parent stikkord:

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

Merk at i dette tilfellet har vi lagt til .base å spesifisere denne siden skal vises under gruppen "Grunnlinje" vist i sidefeltet (du kan også opprette grupper i undernavnet! Vi vil grave inn i det på litt).

Hvis du kjører igjen doksene og oppdaterer siden, skal den se slik ut:

Nå for den kjøttfulle delen! Med vår side på plass kan vi gjøre noen ting:

• Vi kan legge til en generell beskrivelse for dokumentet
• Vi kan legge til alt slags innhold ved hjelp av både markdown eller vanlig HTML
• Og best av alt, kan vi legge til demoer for vår kode?

La oss legge til en rask beskrivelse og en demo for våre 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 tillater å legge til en iframe med en demo til doc. Denne demoen er egentlig bare en enkel HTML-fil med et skript-tag som importerer CSS til appen din på kjøretid.

La oss åpne demoen buttons-custom.html  :

Og se hvordan koden ser ut som:

<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 som kreves i denne filen, er skriptet, som skal være det samme for alle demoer du lager i denne appen. Resten av koden er merket med stilene du vil vise i demoen.

I tillegg kan du bruke taggen @demo å også vise kodebiten som brukes i den. Som dette:

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

Hvilken vil sende ut slik:

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

Nå, før du går bananer med dette, er det et par flere godbiter som du kan dra nytte av:

• Opprette stilavsnitt
• Opprette stilarkgrupper

Opprette stilavsnitt

For å lage en stilavdeling kan du bruke taggen @styles . Denne taggen er søt fordi den lar deg bryte ned stilarkdokumentet ditt i fornuftige biter som du kan snakke om og forstå bedre.

For eksempel, i vårt eksempel har vi stiler for å definere knapper generelt, uavhengig av merkingen som brukes (enten a vs stikkord). Og så har vi definisjoner av farge. Med @styles tag kan vi bryte fargedefinisjonene i sin egen seksjon, ikke bare for å snakke om dem separat, men for å kunne hyperkobling til den delen direkte.

Slik fungerer det. I samme fil buttons-custom.less , vi skal legge til taggen @styles rett etter den første blokken av stiler og før fargevariablene. Slik ser det 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 er et par ting å peke på her:

• Jeg oppdaterte den første demonstrasjonen for å bare vise knappetyper.
• Jeg la til en ny kommentarblokk ved hjelp av @styles stikkord. Her ga jeg det et unikt navn button-colors og tittelen på Button Colors . Jeg ga det også en @description og la til en @demo for det som bare viser knappens farger.

Og her er produksjonen:

Legg merke til at den nye kommentarenblokken nå er en del i "Knapper" -dokumentet, som du også kan få tilgang til direkte ved hjelp av denne url: http://localhost: 8080 / styleguide / buttons-colors.html

Jeg personlig finner dette super nyttig fordi du kan peke folk til en bestemt del i stilguiden, og sier: " er på x-side, under x-delen, så må du bla ... og bla, bla, bla ". I stedet kan du gi en direkte link til den, og slutten av historien.

Opprette stilarkgrupper

I tillegg kan du også opprette seksjoner eller grupper i sidefeltet i stilguiden. For dette, åpne filen styles.md , ligger i markdown katalogen.

Du vil legge merke til her en ny tag kalt @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.

La oss nå bryte ned den andre linjen:

@group

De @group taggen kan du opprette en del i sidefeltet som vises under overordnet seksjon. For eksempel vil gruppene: "Tema" og "Grunnlinje" vises under overordnet seksjon av "Stiler".

styles.theme

Dette er det unike navnet til gruppen. En god praksis å følge her er å bruke navnet på overordnet seksjon, i dette tilfellet "Stiler" som et navneområde. På denne måten, hvis du vil opprette en annen gruppe med samme navn, men under en annen seksjon, forblir gruppenes navn unikt.

0

Dette er rekkefølgen der gruppen skal vises, som starter med 0. Hvis ingen ordre er tildelt, vises listen over grupper i alfabetisk rekkefølge.

Theme

Dette er det faktiske navnet som vil vises i sidefeltet, slik at du kan bruke flere ord med mellomrom og andre tegn.

For å se grupper i aksjon, la vi legge til 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.

Til slutt, la oss legge til et eksisterende dokument under denne nye delen. For dette åpne filen forms-custom.less :

Og på linje 3, erstatt styles.base til styles.forms .

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

Kjør deretter dokumentene og oppdater nettleseren. Du vil nå se "Form Elements" doc under gruppen "Forms" i sidefeltet.

Wrap Up

Living Style Guides er et verktøy for å skape mer konsistente og sammenhengende brukergrensesnitt, og du kan virkelig dra nytte av dem når du bruker Stilguide Driven utviklingsmetode og når du designer på en modulær måte .

Du, bygger levende stil guider på dette punktet!

På dette tidspunktet, hvis du har fulgt med, bør du nå ha en levende Living Style Guide, og en gjennomtenkt plan for å lage en LSG som du kan bruke som utgangspunkt for andre prosjekter.

[- Opprinnelig lagt ut på Bitovi bloggen , publisert med forfatterens tillatelse.<

dokumentasjon dokumentere css levende stil guide LSG stil guider