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.

1-giphy-kramer

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
2-příklad-osamělý-planet

Průvodce stylem Lonely Planet

3-příklad-prodejní síla

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:

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

5-vintage-shop-mockups

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:

6-vintage-shop-prvky

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.

7-vintage-shop-styly

Vsechny tyto body sestavujeme pomocí diagramu:

8-diagram-styl-průvodce-1

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:

9-diagram-styl-průvodce-2

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.

1-giphý

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:

2-terminální server běží

A v prohlížeči:

3-app-home
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:

4-styl-průvodce-Vítejte

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.
6-style-guide-generátor

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

7-projekt-obsah

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:

8-project-content-about

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.

9-styl-průvodce-asi-1

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

@page about [email protected] 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":

10-styl-průvodce-asi-2

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

11-styl-průvodce-asi-3

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 [email protected] 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:

12-style-guide-about-4

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.

1-gify-back-to-the-future

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 .

2-tlačítka-vlastní

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.

3-styl-průvodce-tlačítka-1

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:

4-styl-průvodce-tlačítka-2

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

5-styl-průvodce-tlačítka-3

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  :

6-tlačítka-demo

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:

7-styl-průvodce-tlačítka-4

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