Dokumentera dina designsystem med Fractal

Sep 15, 2025

Hur

Vill du lära dig mer om designsystem? Sedan missa inte senior ui ingenjör Mina Markham på Generera New York Den 28 april, där hon kommer att diskutera hur hon skapade Pantsuit, var designsystemet som drivit många av applikationerna värd på Hillaryclinton.com. Och på västkusten, på Generera San Francisco den 9 juni, Stephanie rewis Kommer dela med sig av de lektioner hon lärde sig när de byggde Salesforce designsystemet.

Nu är många av oss bekanta med stilguider . Men det finns en ny ras av designsystemdokumentation som får ånga: mönsterbiblioteket. Den stora skillnaden mellan de två är den främsta källan till verktygets dokumentation.

En stilguide dokumentation tenderar att härröra från en markdown-fil, så för att visa markeringen författaren är ofta tvungen att kopiera och klistra in den i markeringen. Detta är nästan omöjligt att behålla vid montering av flera komponenter tillsammans.

Ett mönsterbibliotek, å andra sidan, behandlar våra komponent HTML-filer som första klassens medborgare. Varje komponent får sin egen sida, där den visar markeringen och gjort HTML direkt från HTML-filen. Detta garanterar att HTML-filerna och dokumentationen aldrig kommer ut ur synkronisering.

Mönsterbibliotek är ofta byggda med ett mallande språk snarare än vanligt HTML. Mallar kan innehålla variabler och annan logik, då kan vi passera i olika uppsättningar data, vilket möjliggör variationer av en komponent som ska visas.

Det är möjligt att kombinera flera mallar för att skapa mer komplexa skärmar, eller till och med fullständiga sidor. Dessa filer är så flexibla att de till och med kan användas i produktion! Eventuella ändringar som gjorts i vårt mönsterbibliotek hämtas automatiskt av vår hemsida, som alla markeringar - för biblioteket eller för produktion - härstammar från en enda uppsättning av kanoniska mallar.

Design systems will be covered at both Generate New York and San Francisco this year — Designsystem kommer att täckas både generera New York och San Francisco i år

Gå in i fraktal

Skapat av Clesleft, Fraktal Hjälper dig att bygga och dokumentera webbkomponentbibliotek och integrera dem i dina projekt. I den här handledningen kommer vi att titta närmare på hur det fungerar (ladda ner en färdig version av demo på här ).

Fractal är en node.js-modul som är installerad via NPM. Först vill du installera modulen globalt så att du kan generera ett nytt projekt:

npm install --global @frctl/fractal

Med det här paketet installerat, skapa ett nytt projekt:

fractal new project-name

Detta kommando brinner upp en installationsguide som går igenom installationsprocessen. Det kommer att fråga dig om titeln på projektet. namnen på komponenter, dokumentation och offentliga mappar; Och om du ska använda git för versionskontroll. När de här frågorna är färdiga, installerar Fractal alla nödvändiga moduler och ställer in en mappstruktur som anges.

Om du vill hoppa över den globala installationen och skapa projektet manuellt, kan de manuella installationsanvisningarna hittas på här .

Snurra upp det

Nu har du ett helt installerat Fractal-projekt, snurra upp det genom att gå in i projektmappen CD-projektnamn och kör kommandot Fractal Sync. Detta startar en lokal server, tittar på filerna för ändringar och startar automatiskt BrowserSync:

fractal start --sync

Och precis som det har du en arbetsförekomst av fraktal. Öppna din webbläsare av val och navigera till http: // localhost: 3000 För att se början av ditt nya fraktalprojekt. För att undvika att alla ska installera Fractal globalt, skapa ett skript i din paket.json som kallar det fraktala binära.

 "Skript": {
    "Fractal": "./node_modules/.bin/Fractal Start --Sync"
}

Nu kan du använda npm kör fractal utan att behöva installera något globalt.

Lägger till en komponent

Nu har du startat ett fraktalprojekt, det är dags att lägga till några komponenter. Startfilerna kommer med en komponent som heter "Exempel", men vi kommer att bli av med det och göra en ny från början.

En av de bästa sakerna om Fractal är att du kan organisera dina komponenter men du gillar inuti mappen Komponenter, och det kommer automatiskt att mimma den organisationen i mönstret Biblioteksnavigering.

För den första komponenten skapar vi en ny primär knapp inuti a knappmapp . Att göra det, skapa med en mallfil på Komponenter / Knappar / Primärknapp / Primär-Button.hbs . Fractal stöder styrmallar ut ur lådan, så använd .hbs Filförlängning:

  & lt; button class = "primär-knapp" & gt; {{text}} & lt; / knapp & gt;

De {{text}} String inuti knappen är en variabel platshållare, och det här låter dig återanvända mallen, som passerar i olika värden för text från datafilen.

För att skapa datafilen, använd samma basnamn som styrfilen, men med en annan yml förlängning. Nu den primär-button.config.yml sitter inuti Komponenter / Knappar / Primärknappar Mapp ska se ut så här:

 Titel: Primärknapp
sammanhang:
    Text: Klicka på mig

Allt detta tillsammans skapar din första nya komponent, den primära knappen, en medlem i knappkategorin, med texten: "Klicka på mig".

Komponentvariationer

Fractal stöder variationer av samma komponent, så att vi kan visa samma komponent med olika modifieringsklasser eller attribut. Så låt oss säga att vi ville ha möjlighet att använda en mörk tema-knapp. Vi kunde skapa en ny mallfil som heter primärknapp - mörk.hbs Bredvid vår ursprungliga mall (den dubbla strecken betecknar dessa komponentvariationer). I den här mallen tillämpar vi en modifierare vi kan haka för att bifoga nya stilar.

 & lt; knappklass = "Primärknapp" data-tema = "mörk" & gt; {{{text}} & lt; / knapp & gt;

Nu när vi skriver vår CSS kan vi inkludera följande väljare för att ändra den här mallen med modifierande stilar.

 .Primary-knapp [Data-tema = "mörk"] {}

Datavariationer

Precis som vi kan definiera variationer genom att skapa flera mallfiler kan vi också skapa variationer inom våra data. Vi kan göra det inne i primär-button.config.yml filen genom att lägga till en varianter array.

 Titel: Primärknapp
sammanhang:
    Text: Klicka på mig
Varianter:
- Namn: Ladda ner
    sammanhang:
Text: Ladda ner nu
- Namn: Installera
    sammanhang:
Text: Installera nu

Detta kommer att skapa nya variationer som heter "nedladdning" och "installera", med olika text som passerade in i knappen. Ett mer praktiskt exempel kan vara om du använde samma primära-button.hbs Mall i fraktal såväl som produktion. I det här fallet, istället för att skapa en helt ny mall för ditt mörka tema, kan du skicka temavärdet i som en variabel och använda datavärdiga för att visa alla olika knappteman.

 & lt; knappklass = "Primär-knapp" data-tema = "{{theme}}" & gt; / knapp & gt;

Titel: Primärknapp
sammanhang:
    Text: Klicka på mig
    Tema: Ljus
Varianter:
- Namn: Mörk tema
    sammanhang:
Text: Klicka på mig
Tema: Mörk

Hantera andra tillgångar

Fractal kommer också att hantera andra filer än markup och data. Alla CSS, JavaScript, bilder eller andra tillgångar som du lägger till i komponentmappen visas på fliken Tillgångar. Du kan ange en Readme.md Fil för komponenten så att du kan skriva anteckningar om hur komponenten används eller länkar till andra delar av dokumentationen.

Nästa steg

Att upprepa föregående exempel för alla dina kärnkomponenter skapar en användbar katalog över din webbplatss huvudbyggnadsblock. Men den verkliga kraften i ett mönsterbibliotek kommer från förmågan att kombinera dessa bitar tillsammans. Var noga med att kolla in Fractaldokumentation För att lära dig hur du kan börja skapa mer komplexa komponenter genom att kombinera mindre atomelement för att skapa större.

DOCS-mappen är ett bra ställe att sätta traditionell stilguide information och kompletterande anteckningar. Detta kan täcka saker som ombord på dokumentation, riktlinjer för ditt varumärkes röst och ton, listor över färger och variabler, och så vidare. Det följer samma mappbaserad navigering som komponenter gör, och om du organiserar dina filer inom ämnesmappar hittar du navigering av Fractal docs en bris.

Fractal stöder också mer komplexa datakällor. Om du behöver generera en stor uppsättning data för en mall, eller vill dra in den från en tredje part API, kan du använda komponentnamn.config.js För att returnera ett JavaScript-objekt i stället för YML-fildata.

Slutligen tillåter Fractal dig att använda ett antal olika templerande språk.Var noga med att kolla in hela listan i dokumentationen.Och mest av allt, ha kul!

Boka dina biljetter till Generera i dag!I New york Du kan lära av Mina Markham, som byggde designsystemet för Hillary Clintons presidentkampanj och i San Francisco Stephanie Rewis kommer att förklara hur du kan arkitekt och bygga en modern CSS-ram för ett "levande designsystem" i företagsskala.

Denna artikel publicerades ursprungligen i Net Magazine Issue 285, köp det här

Dokumentera dina designsystem med Fractal

Gå in i fraktal

Snurra upp det

Lägger till en komponent

Komponentvariationer

Datavariationer

Hantera andra tillgångar

Nästa steg

Hur - Mest populära artiklar

Hur man tar en skärmdump på en Mac

Hur man skapar tillgängliga webbformulär

Bygg Cross-Platform-mobilappar med Googles fladder

Skapa en animerad ångtexteffekt

Måla en episk New York-scen

Gör en affisch från en mall i Photoshop

Gör en animerad GIF i Photoshop

Snabba upp din 3D-modellering

Kategorier