Jak vytvořit průvodce živým stylem

Použití živého stylového průvodce (LSG) pro řízení vývoje je praxe, která získává hodně popularity, protože má mnoho výhod, včetně efektivity kódu a konzistence uživatelského rozhraní. Ale jak můžete vytvořit jeden? Co byste měli zahrnout? A kde dokonce začnete? V tomto tutoriálu se budu ponořit do drobných detailů vytváření živého stylu DocumentCSS .

Krása průvodce živého stylu

Podobně jako u standardního průvodce styly poskytuje živý stylový průvodce soubor standardů pro použití a tvorbu stylů pro aplikaci. V případě standardního průvodce styly je cílem zachovat soudržnost značky a zabránit zneužití grafických a konstrukčních prvků. Stejným způsobem se LSG používají k udržení konzistence v aplikaci a k ​​vedení jejich implementace. Ale to, co dělá LSG jiný a výkonnější, je, že velká část jeho informací přichází přímo ze zdrojového kódu, takže je snadné a efektivní odrážet vyvíjející se stav aplikace.

Dokonce i dnes je vadit, když se dozvíte, že můžete použít zdrojový kód vaší aplikace pro vytvoření průvodce styly.

Pokud se podíváte na níže uvedené příklady, uvidíte, že společné jmenovatele LSG jsou:

• Seznam dokumentovaných prvků
• Dokonalá dokumentace s úryvky kódu a interaktivní ukázky UI

Průvodce stylem Lonely Planet

Průvodce styly prodeje

Dalším klíčovým prvkem LSG je, že pro automatizaci procesu můžete použít generátor stylového průvodce. Generátor průvodce styly bude používat zdrojový kód aplikace, který bude zásobovat většinu dokumentace LSG a sledovat změny provedené ve vašem kódu, přičemž se bude dbát na aktualizaci dokumentace průvodce styly při změně vaší aplikace.

Generátory generátorů stylů

Existuje mnoho možností, jak si vybrat, v závislosti na jazyku, který chcete dokumentovat, nebo na nastavení projektu. Zde je několik možností, jak hledat možnosti:

• In-Depth Přehled nástrojů pro průvodce živého stylu , Robert Haritonov, Smashing Magazine
• Přehled generátorů knihoven vzorů , David Hund, GitHub
• Různé generátory průvodce , Susan Robertson, A List Apart
• Nástroje průvodce stylů , Zdroje stylů webových stylů

Pro tento tutoriál vám ukážeme, jak můžete pomocí programu DocumentCSS vytvořit LSG. Tento nástroj vytvořený společností Bitovi je otevřený zdroj a může být použit v jakémkoli projektu pro dokumentaci CSS (také jsou podporovány preprocesory jako Méně a SASS). Pokud máte zájem o dokumentaci Javascriptu a jiných jazyků, můžete to snadno provést pomocí programu DocumentCSS, protože tento nástroj je podmnožinou DocumentJS. V tomto tutoriálu tuto část nezahrnuji, ale je dobré mít na paměti.

Plánování Průvodce styly

Předtím, než se ponoříte do vytváření LSG, je prvním krokem plánování toho, co bude v něm. Jako každá dobrá webová stránka je klíčová strukturovaná informační architektura (IE).

Takže začneme s použitím následující sady vzorků vzorové aplikace s názvem "Vintage Shop" a sledujte přetrvávající prvky v uživatelském rozhraní:

Vintage Shop Mockups

V tomto okamžiku doporučuji začít s větším počtem prvků, jako je navigace, vozík nebo formuláře. Například rozdělíme náš design do těchto tří skupin: indikátor kroků, mini vozík a výrobky v košíku:

S těmito většími skupinami prvků můžete začít detailněji a identifikovat "styly", které přetrvávají. Existuje například konvence pro typografii obecně a konkrétněji pro nadpisy, podkapitoly a odkazy versus běžný text. Barva tlačítek také přetrvává po stránkách.

Vsechny tyto body sestavujeme pomocí diagramu:

Při hlubším pohledu na tyto skupiny je můžete jemně naladit a přeměnit je do kategorií, které můžete použít ve svém průvodce stylu, jak roste. Například:

• "Elements" je velmi vágní termín, který by mohl odkazovat na libovolný element HTML, takže lepší název pro tuto skupinu by mohl být "Komponenty" nebo "Moduly". Jsou to ještě obecné pojmy, ale jsou specifičtější podle povahy typu prvků, které by zahrnovaly.
• Tlačítka "Primární vs. sekundární" mohou být součástí "Základních prvků" a jeho barevný aspekt by mohl být zařazen do kategorie "Paleta barev".

Navíc můžete přemýšlet o kategorii, kde můžete zahrnout více obecných informací o vašem průvodce stylu. Dobrým příkladem by byla část "Průvodci", kde byste mohli popsat, jak přispívat ke stylu průvodce nebo sekci Branding, kde můžete zahrnout pokyny o vaší značce, které byste měli mít při plánování a implementaci aplikace.

Vzhledem k tomu máte na paměti, jak vypadá tato schéma:

Můžete vidět, jak tento diagram přebírá podobu mapy stránek, což je v podstatě to, co chcete použít jako plán při vytváření živého průvodce.

Nyní se ponořte do návrhů a nakreslete svou vlastní mapu stránek, včetně mnoha kategorií, o kterých si myslíte, že by byly užitečné pro budoucnost. Můžete získat nápady z jiných průvodců stylu ( styleguides.io/examples je skvělý zdroj). Až budete hotovi, zkontrolujte tuto komplexnější verzi a porovnejte ji.

Vytváření stránek v Průvodci živým stylem

Zatímco většina dokumentace LSG pochází ze speciálních komentářů, které přidáte do zdrojového kódu, můžete také vytvářet samostatné stránky, kde můžete hostit jiné typy obsahu, které nejsou specifické pro kód (přemýšlejte o zásadách návrhu, pokynech pro usnadnění přístupu, nebo vyžádat pokyny pro vyžádání). To vám dává přednost centralizaci vaší dokumentace na jednom místě: Průvodce stylu bydlení aplikace.

Můžete si téměř myslet na průvodce živého stylu jako "pravidla hry" vaší aplikace. Uvnitř "pravidel" jsou všechny informace, které je třeba o tom, jak hrát hru: Budovy a pravidla pro vytváření a vytváření nových bloků. Včetně toho, jak k tomu přispívají ostatní členové vašeho týmu a pomáhají je udržovat jako živý dokument.

_{Yas! Věř tomu. Všechny své dokumenty můžete mít na jednom místě!}

Vzhledem k tomu je třeba začít instalací ukázkové aplikace, kterou budeme používat pro tento výukový program.

Instalace ukázkové aplikace

Proces instalace má 3 kroky:

1. Instalace uzlu

Nejprve se ujistěte, že máte Uzel nainstalován. Budete potřebovat alespoň verzi 6.

2. Instalace aplikace

Poté stáhněte tento soubor zip: sgdd-tutorial.zip na pracovní plochu a rozbalte jej . To je důležité, jelikož jiné umístění naruší instalační příkazy.

Pak otevřete terminál a zadejte následující příkaz:

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

Instalace aplikace a její závislosti bude trvat několik sekund.

3. Spuštění aplikace

Po dokončení instalace zadejte následující příkazy:

1. npm run develop
2. Na nové kartě zadejte: npm run document

Nyní to rozdělíme:

npm run develop

Spustí server, kde můžete vidět aplikaci spuštěnou na adrese: http://localhost: 8080. Uvidíte v terminálu:

A v prohlížeči:

npm run document

Generuje průvodce živého stylu na http://localhost: 8080 / styleguide. Příznak můžete přidat -- -w k tomuto příkazu sledovat změny ve vašem kódu a pak generovat aktualizaci v živém stylu průvodce, jako je toto:

npm run document -- -w

Při přepnutí na prohlížeč byste měli vidět:

Generuje průvodce živého stylu DocumentCSS , takže se podívejme, jak to funguje.

Jak funguje DocumentCSS?

DocumentCSS je statický generátor stránek. To znamená, že hledá speciálně formátované komentáře ve vašem kódu a vytvoří statické webové stránky. Tato stránka se nazývá "statická", protože zůstává nezměněna, dokud příkaz (v tomto případě dokumentů ) znovu spustit. Tento pracovní postup funguje dobře při vytváření živého stylového průvodce, protože změny ve vašich stylových listech jsou také změnami statického webu Living Style Guide.

Chcete-li vytvořit průvodce živým stylem, provede DocumentCSS následující:

• Čte soubory, které jsou uvedeny v jejich konfiguraci (pro tento tutoriál se bude dívat na .less a .md soubory)
• Vyhledává komentáře, které používají speciální "značky" (například @page , @stylesheet nebo @styles .
• Generuje html soubory a připojí je k vytvoření webu.

S tímto zaměřením se přeskočíme do dokumentu DocumentCSS, abychom vytvořili novou stránku v LSG.

Vytvoření stránky

Nejprve otevřete ukázkovou aplikaci v editoru kódu. Měli byste vidět následující strukturu souborů:

Vrtajte se do src a najděte base/markdown . Zde najdete stránky, které již existují ve stylu průvodce. Vytvořte nový značkovací soubor a pojmenujte jej "o" (s příponou .md ). Souborová struktura by nyní měla vypadat takto:

Uvnitř tohoto nového souboru přidejte značku @page následované dvěma řetězci:

@page about about

Teď to rozbijeme:

@page

Značka @page deklaruje soubor jako stránku a informuje DocumentCSS, že informace v tomto souboru by měly být zobrazeny jako stránka ve stylu průvodce. To slouží k odlišení od stylových listů, javaskriptů nebo jiných typů souborů ve vaší dokumentaci.

about

Jedná se o jedinečný název stránky a slouží jako odkaz na jiné značky. Takže je to krátké, malé a jednoduché, protože bude použito jako adresa URL stránky. Pro náš příklad bude adresa URL naší nové stránky: http://localhost: 8080 / styleguide / about.html

About

Toto je název stránky, která bude použita k zobrazení na vygenerovaném webu. Zde můžete použít více slov s mezerami nebo jinými znaky.

Chcete-li zobrazit nově vytvořené stránky, spusťte dokumenty v terminálu znovu (pokud nemáte sledování změn) a pak přejděte na http://localhost: 8080 / styleguide / about.html pro zobrazení nové stránky.

Dalším krokem je přidání stránky do navigace. K tomu přidejte do souboru následující druhý řádek:

@page about About@parent index

Značka @parent umožňuje zadat nadřazený dokument. V tomto případě chceme, aby se stránka "Informace" zobrazovala pod domovskou sekcí. Nyní můžete znovu spustit dokumenty a zobrazit stránku zobrazenou pod odkazem "Vítejte":

A pokud kliknete na odkaz "Vítejte", získáte přístup k úvodní stránce:

Nyní je dobré přidat obsah na tuto stránku pomocí markdown nebo html. Chcete-li dokončit cvičení, přidejte následující fiktivní obsah:

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

A tady je výstup:

Dokumentování stylu v Průvodci živým stylem

Srdcem vytváření LSG je schopnost dát dokumentaci přímo tam, kde patří: ve zdrojovém kódu. Je pravděpodobné, že již dokumentujete svůj kód, což je skvělá příležitost, jak ji převést na další úroveň pomocí generátoru stylových pokynů, který může tyto připomínky přenést na organizovanou stránku a nechat ostatní (a sebe od budoucnosti) vědět proč a co bylo provedeno v kódu.

Sami z budoucnosti po přečtení dokumentů, které jste napsali v minulosti.

Dokumentace stylu

Dokumentování stylu se podobá vzoru dokumentaci stránky , ale v tomto případě se dokumentace dostane do komentáře, hned vedle kódu (to je krása!).

Začněte otevřít styl stylu: buttons-custom.less .

Uvnitř tohoto souboru a uvnitř bloku poznámek přidejte značku @stylesheet následované dvěma řetězci:

/**@stylesheet buttons.less Buttons*/

Poznámka: poznámka k dokumentaci musí začínat /** pro analyzátor (v tomto případě JSDoc ), aby ji rozpoznali.

Teď to rozbijeme:

@stylesheet

Značka @stylesheet deklaruje soubor jako stylový list a říká DocumentCSS že informace v tomto souboru by měly být ve stylu průvodce zobrazeny. To slouží k odlišení od jiných typů dokumentů, například stránek, komponent a modelů ( Zde si přečtěte celý seznam typů dokumentů ).

buttons.less

Jedná se o jedinečný název šablony stylů a slouží jako odkaz na jiné značky. Zatímco můžete použít libovolný typ názvu, doporučuji použít název souboru stylesheet, protože to pomůže při hledání odkazu na dokumentaci. Nezapomeňte, že to ovlivní adresu URL vašeho dokumentu. U tohoto příkladu bude adresa URL: http://localhost: 8080 / styleguide / buttons.less.html

Buttons

Podobný vytvoření stránky , toto je název stylu listu, který bude použit pro zobrazení na vygenerovaném webu. Zde můžete použít více slov s mezerami nebo jinými znaky.

Chcete-li zobrazit nově vytvořenou stránku, spusťte následující příkaz, pokud nemáte sledování změn):

documentjs

A pak jdi http://localhost: 8080 / styleguide / buttons.less.html pro zobrazení nové stránky.

Nyní přidáme tento nový dokument do naší navigace. Pro toto budeme dodržovat stejnou konvenci, kterou jsme použili při vytváření stránky pomocí @parent štítek:

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

Všimněte si, že jsme v tomto případě přidali .base zadání této stránky by se mělo objevit pod skupinou "Baseline" zobrazené na postranním panelu (můžete také vytvořit skupiny ve vaší podnabídce).

Znovu spustit dokumenty a obnovit stránku by měla vypadat takto:

Nyní pro masovou část! Díky naší stránce si můžeme udělat pár věcí:

• Pro dokument lze přidat celkový popis
• Můžeme přidávat všechny druhy obsahu pomocí markdown nebo prostého HTML
• A nejlépe můžeme přidat náš kód?

Přidejte stručný popis a demo pro naše tlačítka 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*/

Obnovit dokumenty a?:

Jak vidíte @iframe tag umožňuje přidávat do dokumentů iframe s demo. Toto demo je opravdu jen jednoduchý html soubor se značkou skriptu, která během běhu importuje CSS vaší aplikace.

Otevřete demo buttons-custom.html  :

A podívejte se, jak vypadá kód:

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

Jediné, co se v tomto souboru vyžaduje, je značka skriptu, která by měla být stejná pro jakékoli demo, které vytvoříte v této aplikaci. Zbytek kódu je označením stylů, které chcete zobrazit v ukázce.

Navíc můžete tag použít @demo také zobrazit úryvek kódu, který je v něm použit. Takhle:

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

Kdo bude vypadat takto:

Demo úvěr jde Bootstrap Docs odkud je kód zkopírován.

Teď, než půjdete s tímto banáním, je zde několik dalších dobrot, které můžete využít:

• Vytváření sekcí stylů
• Vytváření skupin stylů

Vytváření sekcí stylů

Chcete-li vytvořit sekci stylu, můžete použít značku @styles . Tato značka je sladká, protože vám umožňuje rozdělit styly dokumentů do rozumných kusů, o kterých můžete mluvit a porozumět jim lépe.

Například v našem příkladu máme styly pro definování tlačítek obecně, bez ohledu na značku, která se používá (a vs štítek). A pak máme definice barvy. S @styles tagu můžeme rozdělit definice barev do jejich vlastní sekce, a to nejen o tom, že o nich mluvíme samostatně, ale abychom byli schopni přímo odkazovat na tuto sekci.

Tak funguje. Ve stejném souboru buttons-custom.less , přidáme značku @styles hned po prvním bloku stylů a před barevnými proměnnými. Zde je návod, jak by to mělo vypadat:

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

Zde je několik věcí, na které byste měli poukázat:

• Aktualizoval jsem první ukázku a ukázal pouze ty typy tlačítek.
• Přidala jsem nový blok komentářů pomocí příkazu @styles štítek. Zde jsem mu dal jedinečný název button-colors a název Button Colors . Dal jsem jí také @description a přidal a @demo pro to, že zobrazuje pouze barvy tlačítek.

A tady je výstup:

Všimněte si, že nový blok poznámek je nyní v sekci "Buttons" doc, ke které můžete také přistupovat přímo pomocí této adresy URL: http://localhost: 8080 / styleguide / buttons-colors.html

Já osobně považuji za velmi užitečné, protože můžete přenést lidi na určitou sekci ve stylu průvodce, když říká: " je v x stránce, pod sekcí x, pak musíte posunout ... a bla, bla, bla ". Místo toho mu můžete poskytnout přímý odkaz a konec příběhu.

Vytváření skupin stylů

Navíc můžete také vytvářet oddíly nebo skupiny v postranním panelu Průvodce styly. K tomu otevřete soubor styles.md , umístěný v markdown adresář.

Zde si všimnete novou značku nazvanou @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.

Nyní rozdělíme druhý řádek:

@group

The @group značka umožňuje vytvořit sekci v postranním panelu, který se zobrazí pod nadřazenou sekcí. Skupiny například: "Téma" a "Výchozí hodnota" se zobrazí pod nadpisem "Styly".

styles.theme

Toto je jedinečný název skupiny. Dobrou praxí, která následuje, je použít název nadřazené sekce, v tomto případě "styly" jako jmenný prostor. Tímto způsobem, chcete-li vytvořit jinou skupinu se stejným názvem, ale v jiné části, zůstane jméno skupiny jedinečné.

0

Toto je pořadí, ve kterém se má zobrazit skupina, která začíná číslem 0. Pokud není přiřazena žádná objednávka, zobrazí se seznam skupin v abecedním pořadí.

Theme

Toto je skutečné jméno, které se zobrazí v postranním panelu, takže můžete použít více slov s mezerami a jinými znaky.

Chcete-li zobrazit skupiny v akci, přidejte novou skupinu takto:

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

Nakonec přidáme do této nové části existující dokument. Otevřete soubor forms-custom.less :

A na řádku 3 nahraďte styles.base pro styles.forms .

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

Potom spusťte dokumenty a obnovte prohlížeč. Nyní se v bočním panelu zobrazí formulář "Formulářové prvky" pod skupinou "Formuláře".

Zabalit

Životní styl Průvodce jsou nástroj pro vytvoření konzistentnější a soudržné uživatelské vzory, a můžete opravdu využít z nich při použití Průvodce výstupem řízeným stylem průvodce a při navrhování v modulární cestě .

dokumentace dokumentace css životní styl průvodce lsg stylů