Dokumentér dine designsystemer med fraktal

Sep 13, 2025

hvordan

Har du lyst til at lære mere om designsystemer? Så gå ikke glip af Senior UI Engineer Mina Markham. på Generere New York. Den 28. april, hvor hun vil diskutere, hvordan hun skabte pantsuit, designsystemet, der drev mange af applikationerne, hostede på Hillaryclinton.com. Og på vestkysten, på Generere San Francisco. den 9. juni, Stephanie rewis. Vil dele nogle af de lektioner, hun lærte, mens du byggede Salesforce Design System.

På nuværende tidspunkt er mange af os bekendt med Style Guides . Men der er en ny race af designsystemdokumentation, der får damp: Mønsterbiblioteket. Den største forskel mellem de to er den primære kilde til værktøjets dokumentation.

En stilguide dokumentation har tendens til at stamme fra en markdown-fil, så for at vise Markupen er forfatteren ofte tvunget til at kopiere og indsætte den i markeringen. Dette er næsten umuligt at opretholde ved montering af flere komponenter sammen.

Et mønsterbibliotek behandler på den anden side vores komponent HTML-filer som førsteklasses borgere. Hver komponent får sin egen side, hvor den viser markeringen og gengivet HTML direkte fra HTML-filen. Dette sikrer, at HTML-filerne og dokumentationen aldrig kommer ud af synkronisering.

Mønsterbiblioteker bygges ofte ved hjælp af et templateringssprog frem for almindelig HTML. Skabeloner kan omfatte variabler og anden logik, så vi kan passere i forskellige sæt data, hvilket gør det muligt at vise variationer af en komponent.

Det er muligt at kombinere flere skabeloner for at skabe mere komplekse skærme eller endda fulde sider. Disse filer er så fleksible, de selv kunne bruges i produktion! Eventuelle ændringer i vores mønsterbibliotek afhentes automatisk af vores hjemmeside, som alle markup - til biblioteket eller til produktion - stammer fra et enkelt sæt kanoniske skabeloner.

Design systems will be covered at both Generate New York and San Francisco this year — Designsystemer vil blive dækket på begge generere New York og San Francisco i år

Indtast fraktal

Skabt af CleartLet, Fraktal Hjælper dig med at opbygge og dokumentere webkomponentbiblioteker og integrere dem i dine projekter. I denne tutorial vil vi se nærmere på, hvordan det virker (download en færdig version af demoen på her ).

Fractal er et node.js modul, der er installeret via NPM. Først vil du installere modulet globalt, så du kan generere et nyt projekt:

npm install --global @frctl/fractal

Med denne pakke installeret, opret et nyt projekt:

fractal new project-name

Denne kommando brænder op en installationsvejledning, der går gennem installationsprocessen. Det vil bede dig om projektets titel; navnene på komponenter, dokumentation og offentlige mapper; Og hvis du bruger git til versionskontrol. Når disse spørgsmål er færdige, vil Fractal installere alle de nødvendige moduler og oprette en mappestruktur lige som angivet.

Hvis du vil springe over den globale installation og oprette projektet manuelt, kan manuel installationsvejledning findes på her .

Spinning det up.

Nu har du et fuldt installeret fraktalprojekt, spin det op ved at træde ind i projektmappen CD Project-Name og kører kommandoen fraktal synkronisering. Dette starter en lokal server, ser filerne til ændringer og starter automatisk BrowserSync:

fractal start --sync

Og ligesom det har du fået en arbejdsinstans af fraktal. Åbn din browser af valg og naviger til http: // localhost: 3000 for at se starten på dit nye fraktalprojekt. For at undgå at kræve, at alle installerer fraktal globalt, skal du oprette et script i din Package.json. der kalder fraktal binær.

 "scripts": {
    "Fractal": "./node_modules/.bin/fractal start -Sync"
}

Nu kan du bruge npm køre fraktal uden at skulle installere noget globalt.

Tilføjer en komponent.

Nu har du startet et fraktalprojekt, det er på tide at tilføje nogle komponenter. Startfilerne leveres med en komponent kaldet 'eksempel', men vi kommer til at slippe af med det og lave en ny fra bunden.

En af de bedste ting om Fractal er, at du kan organisere dine komponenter, men du kan lide inde i mappen Components, og den vil automatisk efterligne den organisation i mønsterbiblioteksnavigationen.

For den første komponent skaber vi en ny primær knap inde i a Knap mappe . For at gøre det skal du oprette med en skabelonfil på Komponenter / Knapper / Primary-Button / Primary-Button.hbs . Fractal understøtter Håndtagskabeloner ud af boksen, så brug .hbs. Filforlængelse:

  & lt; knap klasse = "primær-knap" & gt; {{text}} & lt; / knap & gt;

Det {{tekst}} String inde i knapmærket er en variabel pladsholder, og det lader dig genbruge skabelonen og passere i forskellige værdier for tekst fra datafilen.

For at oprette datafilen skal du bruge det samme basisnavn som håndtagfilen, men med en anden YML. udvidelse. Nu primære-knap.config.ym sidder inde i Komponenter / knapper / primære-knapper mappen skal se sådan ud:

 Titel: Primærknap
sammenhæng:
    Tekst: Klik på mig

Alt dette sammen opretter din første nye komponent, den primære knap, et medlem af knappen Knapkategori, med teksten: 'Klik på mig'.

Komponentvariationer

Fractal understøtter variationer af samme komponent, så vi kan vise den samme komponent med forskellige modifikatorklasser eller attributter. Så lad os sige, at vi ønskede at få mulighed for at bruge en mørk tema-knap. Vi kunne oprette en ny skabelonfil kaldet Primær-knap - Dark.hbs Ved siden af vores originale skabelon angiver den dobbelte dash disse komponentvariationer). I denne skabelon anvender vi en modifikator, vi kan kroge ind for at vedhæfte nye stilarter.

 & LT; Button Class = "Primary-knappen" Data-tema = "Dark" & GT; {{TEXT}} & LT; / Button & GT;

Nu, når vi skriver vores CSS, kan vi medtage følgende vælger for at ændre denne skabelon med modificerende stilarter.

 .Primary-knappen [Data-tema = "Dark"] {}

Datavariationer

Ligesom vi kan definere variationer ved at oprette flere skabelonfiler, kan vi også oprette variationer inden for vores data. Vi kan gøre dette inde i primære-knap.config.ym fil ved at tilføje et varianter array.

 Titel: Primærknap
sammenhæng:
    Tekst: Klik på mig
Varianter:
- Navn: Download
    sammenhæng:
Tekst: Download nu
- Navn: Installer
    sammenhæng:
Tekst: Installer nu

Dette vil skabe nye variationer, der hedder 'Download' og 'Installer', med en anden tekst, der passeres i knappen. Et mere praktisk eksempel kan være, hvis du brugte det samme primære-knap.hbs. skabelon i fraktal såvel som produktion. I dette tilfælde, snarere end at oprette en helt ny skabelon til dit mørke tema, kan du sende temaværdien i som en variabel og bruge datavariationerne til at vise alle de forskellige knaptemaer.

 & LT; Button Class = "Primary-knappen" Data-tema = "{{Tema}}" & GT; {{TEXT}} & LT; / Button & GT;

Titel: Primærknap
sammenhæng:
    Tekst: Klik på mig
    Tema: Lys
Varianter:
- Navn: Dark Tema
    sammenhæng:
Tekst: Klik på mig
Tema: Mørk

Håndtering af andre aktiver

Fractal vil også håndtere andre filer end markering og data. Enhver CSS, JavaScript, billeder eller andre aktiver, du tilføjer til komponentmappen, vises i fanen 'Aktiver'. Du kan angive en Readme.md. Fil for komponenten, så du kan skrive noter om, hvordan komponenten bruges, eller link til andre dele af dokumentationen.

Næste skridt

Gentagelse af det foregående eksempel for alle dine kernekomponenter skaber et nyttigt katalog af dit websteds hovedbygger. Men den reelle kraft i et mønsterbibliotek kommer fra evnen til at kombinere disse stykker sammen. Sørg for at tjekke Fraktal dokumentation For at lære, hvordan du kan begynde at skabe mere komplekse komponenter ved at kombinere mindre atomelementer for at skabe større.

DOCS-mappen er et godt sted at sætte traditionelle stilguide oplysninger og supplerende noter. Dette kan dække ting som ombord på dokumentation, retningslinjer for dit mærke stemme og tone, lister over farver og variabler, og så videre. Det følger den samme mappebaserede navigation som komponenter gør, og hvis du organiserer dine filer inden for fagmapper, finder du navigering af Fraktal docs. en brise.

Fractal understøtter også mere komplekse datakilder. Hvis du har brug for at generere et stort sæt data til en skabelon, eller ønsker at trække den ind fra nogle tredjeparts API, kan du bruge komponent-name.config.js. For at returnere et JavaScript-objekt i stedet for YML-fildataene.

Endelig giver FRACTAL dig mulighed for at bruge en række forskellige templateringssprog.Sørg for at tjekke den fulde liste i dokumentationen.Og mest af alt har det sjovt!

Book dine billetter til Frembringe i dag!I New York. Du kan lære af Mina Markham, der byggede designsystemet til Hillary Clintons præsidentkampagne og i San Francisco. Stephanie Rewis vil forklare, hvordan du kan arkitekt og bygge en moderne CSS-ramme for et 'levende designsystem' på Enterprise Scale.

Denne artikel blev oprindeligt offentliggjort i Net Magazine Issue 285, Køb det her

Dokumentér dine designsystemer med fraktal

Indtast fraktal

Spinning det up.

Tilføjer en komponent.

Komponentvariationer

Datavariationer

Håndtering af andre aktiver

Næste skridt

hvordan - Mest populære artikler

Opret et multi-eksponeringsbillede med Adobe CC

Opret sæt af produktikoner i Illustrator

Colourise Greyscale arbejde i Photoshop

Sådan tegner du med affinitetsfoto til iPad

Sådan sculpt en 3D-trykt goblin

Byg en simpel musikafspiller med reagere

Prep dit arbejde til 3D-udskrivning: 8 Top Tips

Oplev underpainting og hvordan man bedst udnytter den

Kategorier