DESIGN.md loomine

Loo DESIGN.md ühe toote või ühtse veebisaidi jaoks. Pane kirja disainikeel, mis seda juhib, mitte iga väärtus, mis juhtumisi olemas on.

Piirid

• Muuda ainult faili DESIGN.md. Ära muuda toote lähtekoodi, sõltuvusi, konfiguratsiooni ega genereeritud faile.
• Kasuta allpool kirjeldatud DESIGN.md vormingulepingut. Ära leiuta konkureerivat skeemi.
• Ära kopeeri dokumenti iga leitud tokenit ega komponenti.
• Ära muuda kordust, kohalikku stiili ega visuaalset eelistust toote kavatsuseks.

1. Vali režiim

Repositooriumirežiim

Kasuta siis, kui kohalik toote repositoorium on saadaval. Loo või uuenda DESIGN.md valitud toote juurkaustas.

Kui repositooriumis on mitu juurutatavat toodet, vali see, mille kasutaja nimetas. Kui päring ühtegi ei määra ja omandisuhe on ebaselge, küsi enne kirjutamist.

Repositooriumi tõendid võivad kehtestada normatiivsed väärtused, tokenite nimed, komponentide omandi ja dokumenteeritud põhjenduse.

URL-režiim

Kasuta siis, kui kasutaja annab avaliku URL-i ilma selle lähtekoodi repositooriumita. Loo praegusesse tööruumi rekonstrueeritud DESIGN.md mustand.

URL-režiim nõuab ligipääsu renderdatud brauserivaatele. Uuri DOM-i, arvutatud stiile ja avalikult laaditud stiililehti nii lauaarvuti kui ka mobiili laiusel. Ekraanipildid võivad tõlgendamist toetada, kuid ei saa üksi täpseid väärtusi kindlaks teha.

Uuri antud lehte ja jagatud raami (chrome). Kogu saiti puudutava päringu korral võta valimisse kuni kolm sama päritoluga lehte, mis esindavad erinevaid malle.

URL-i tõendid võivad kehtestada ainult jälgitavaid visuaalseid mustreid ja arvutatud väärtusi. Need ei saa kehtestada sisemisi tokenite nimesid, komponentide omandit, dokumenteerimata põhjendusi ega seda, kas muster on teadlikult kanooniline.

Kui renderdatud vaatluse võimalust pole, küsi ekraanipilte või lähtefaile. Ära loo DESIGN.md-d ainult teksti, metaandmete või HTML-struktuuri põhjal.

Vali repositooriumirežiim alati, kui lähtekood on saadaval. Antud URL võib kinnitada renderdatud esitlust, kuid ei asenda repositooriumi tõendeid.

Ühine tõendite töövoog

Režiimid erinevad ainult selle poolest, kuidas nad tõendeid koguvad. Mõlemad peavad kasutama sama kirje- ja väljundtöövoogu:

role → value → source → scope → recurrence → confidence

1. Kogu tõendid valitud režiimi abil.
2. Pane iga kandidaadi kohta kirja allikas, ulatus ja kordumine.
3. Normaliseeri kandidaadid DESIGN.md skeemi.
4. Jäta välja kandidaadid, mis on ebakindlad, kohalikud ilma lepinguta või teostuse seisukohalt ebaolulised.
5. Valideeri frontmatteri kuju ja ekspordi ühilduvus.
6. Kirjuta Markdown alles siis, kui normaliseeritud frontmatter on kontrolli läbinud.

Ära kunagi lase repositooriumi ega URL-i tõenditel tuua sisse teist tokeniskeemi. Mõlemale režiimile kehtivad samad lamedad tokenite nimed, kaardikujuline (mapping) tüpograafia, väljajätmise reeglid ja ekspordiväravad.

Genereeritud dokument on privaatne, kuni valideerimine on läbitud. Ära kunagi tagasta, kuva ega kokkuvõtlikult esita DESIGN.md mustandit enne, kui lint ja eksport õnnestuvad. Kui valideerimine teatab vigasest kujust või puuduvast ekspordikategooriast, kirjuta frontmatter ümber ja käivita uuesti; kui kategooriat ei saa parandada, eemalda see ja teata sellest kui väljajäetust.

2. Jälgi tõendeid

Repositooriumirežiimis uuri järgmises järjekorras:

1. Olemasolev DESIGN.md ja repositooriumi selgesõnalised juhised
2. Tokenid, teemad, muutujad ja globaalsed stiilid
3. Jagatud primitiivid ja nende variandid
4. Esinduslikud marsruudid ja renderdatud tarbijad
5. Pinnapõhised kohalikud teostused

Allikas osaleb ainult siis, kui valitud toode seda impordib, sellele viitab, sellest pärib või seda renderdab. Jäta välja ettepanekud, migratsioonid, näited, genereeritud väljundid, pärandteostused ja sarnase nimega paketid, välja arvatud juhul, kui valitud toode neid kasutab.

URL-režiimis võta esinduslikke elemente valimisse järgmiste kohta:

• värvid ja pindade rollid
• tüpograafia rollid
• vahed ja paigutus
• äärised, raadiused ja kõrgus (elevation)
• navigeerimine, nupud, sisendid, kaardid ja korduvad sisustruktuurid
• esitlus lauaarvutis ja mobiilis

Eelista arvutatud väärtusi ja laaditud CSS-deklaratsioone visuaalsele hinnangule.

Enne URL-režiimi proosa või YAML-i koostamist loo iga valimisse võetud lehe ja vaateava kohta privaatne tõendiregister. Pane iga kandidaadi kohta kirja: leht, vaateava, elemendi roll, arvutatud omadus/väärtus ning võimalusel vastav laaditud CSS-deklaratsioon või kohandatud omadus (custom property). Uuri lehe laaditud avalikke stiililehti, sh kohandatud omadusi ja meediapäringute reegleid; stiililehe väärtus on kasutatav ainult siis, kui see on seotud renderdatud elemendiga või kordub valimi lehtedel.

Tõsta URL-i väärtus DESIGN.md-sse siis, kui kas (a) renderdatud arvutatud väärtus ja laaditud deklaratsioon/kohandatud omadus ühtivad või (b) sama arvutatud väärtus kordub sama rolli puhul kõigis nõutud valimites. Kui kumbki tingimus ei kehti, jäta väärtus välja. Avaldatud kohandatud omaduse nime võid säilitada ainult siis, kui selle deklaratsioon ja renderdatud kasutus on otseselt jälgitavad; ära leiuta toorväärtusest semantilisi aliasi.

Iga URL-režiimi väite puhul nõua enne kirjutamist kõiki kolme tõendit:

1. Vaatlus: muster või väärtus on renderdatud lehel nähtav või arvutatud.
2. Alus: see on mõõdetud või kordub nõutud valimi lehtedel/vaateavades.
3. Tagajärg: see muudab DESIGN.md-s konkreetset teostusvalikut.

Kui mõni tõend puudub, jäta väide välja. Ära muuda visuaalset muljet tokeniks, üksikut esinemist kogu saiti hõlmavaks reegliks ega oletatud väärtust YAML-iks. Täpsed väärtused nõuavad arvutatud stiile või laaditud CSS-i; muul juhul kirjelda rolli ilma väärtuseta või jäta see välja.

3. Otsusta, mis kuulub sisse

Repositooriumirežiimis leia enne toote iseloomu kirjeldamist selgesõnaline toote kavatsus või disainiviide. URL-režiimis ära leiuta toote iseloomu; ülevaade (Overview) võib kirjeldada ainult saidi jälgitavat eesmärki ja esitlust ning peab märkima dokumendi rekonstrueerituks.

Kirjuta YAML ainult juhtivates allikates olevate nimetatud jagatud tokenite ja rollide põhjal. Ära muuda utiliitklasse, korduvaid literaale ega komponentide väärtusi tokeniskaaladeks.

Käsitle frontmatteri kuju range väravana, mitte stiilivalikuna: väärtus, mis on tokenirühm, peab olema kaart (mapping), mille alamelemendid on skeemi väljad. Ära kunagi väljasta skalaarseid tüpograafiakirjeid (sans: Geist), suvalisi pesastatud lähteobjekte (font-family: { mono: ... }) ega CSS-muutujate nimedest kopeeritud ümarduse võtmeid (radius-sm, radius-md jne).

Kasuta tokenirühmade jaoks kaarte, mitte kunagi jadasid. Kui juhtiv allikas määratleb ühe rühmataseme tokeni, näiteks --radius, normaliseeri see kujule base; muul juhul säilita allika tokenite nimed.

Kaardista lähteväärtused DESIGN.md skeemi väljadele. Säilita semantilised tokenite nimed, mitte allika objektide pesastus. Näiteks kirjuta typography.mono.fontFamily: Geist Mono, mitte kunagi typography.mono: Geist Mono; kirjuta rounded.base: 0.625rem, kui allikal on ainult --radius, mitte kunagi rounded.radius ega tuletatud raadiusesamme.

Lahenda raamistiku utiliidid aktiivse teema või konfiguratsiooni kaudu enne täpsete väärtuste kirjutamist.

Tuvasta enne frontmatteri kirjutamist repositooriumi ekspordisiht: css-tailwind Tailwind v4 puhul, json-tailwind Tailwind v3 puhul ja muul juhul dtcg. Tokenite nimed peavad selle sihi jaoks kehtivad olema.

Enne teemarežiimide kodeerimist kontrolli paigaldatud DESIGN.md spetsifikatsiooni:

npx @google/design.md spec

Kui spetsifikatsioon toetab themes ja default-theme, kasuta selle teemateadlikku tokenisüntaksit. Muul juhul pane vaiketeema väärtus iga kanoonilise semantilise tokeni alla ja säilita alternatiivsete teemade täpsed väärtused tabelis ## Themes. Ära loo paralleelseid -light ja -dark tokenite nimesid, ära jäta alternatiivsete teemade väärtusi kõrvale ega kasuta avaldamata süntaksit. Varulahendusena kasutatav Themes-tabel on ainult dokumentatsioon; ära teeskle, et see teeb frontmatteri teemateadlikuks.

Repositooriumirežiimis peab iga proosareegel olema toetatud selgesõnalise juhise, nimetatud jagatud tokeni või variandi või vähemalt kahes auditeeritud pinnas kasutatava jagatud omaniku poolt. Muul juhul jäta see välja.

URL-režiimis peab iga proosareegel olema otseselt jälgitav. Kogu saiti hõlmav reegel peab korduma vähemalt kahes valimisse võetud mallis; muul juhul piira see uuritud lehega. Kasuta rekonstrueeritud rollipõhiseid nimesid ja märgi dokument mustandiks.

URL-režiimi YAML on teadlikult hõre, kuid mitte tühi, kui mõõdetud tõendid on olemas. Lisa kategooria, kui vähemalt üks toetatud väärtus või roll läbib kolme tõendi värava. Värvid võivad kasutada arvutatud väärtusi või kontrollitud avalikke kohandatud omadusi, kuid peavad jääma lamedaks ja ekspordikindlaks; tüpograafia peab kasutama kanoonilisi välju nagu fontFamily, fontSize, lineHeight ja fontWeight; ümarduse ja vahede väärtused peavad pärinema arvutatud stiilidest või laaditud deklaratsioonidest. Ära loo aliasi nagu primary, elevated või display lihtsalt vaatluste korrastamiseks. Komponendijaotis nõuab, et sama interaktsioon või pinnakäsitlus korduks vähemalt kahel valimi lehel ja muudaks konkreetset teostusvalikut.

URL-i rekonstrueerimine ei muuda frontmatteri skeemi. Kasuta ainult neid tüpograafia omaduste nimesid: fontFamily, fontSize, lineHeight, fontWeight ja letterSpacing. Näiteks:

typography:
  sans:
    fontFamily: Inter Variable
  display:
    fontFamily: Inter Variable
    fontSize: 64px
    lineHeight: 64px
    fontWeight: 510

Ära kunagi väljasta URL-spetsiifilisi aliasi nagu family, size, weight, mobile-display ega pesastatud sans/mono väärtusi tüpograafiaskaala sees. Rekonstrueeritud rollinimed võivad erineda; skeemi väljanimed mitte.

URL-väljundi puhul kasuta ühilduvuse ekspordisihina css-tailwind, kui kasutaja ei määra teist sihti. Lameda rekonstrueeritud värvirollid kehtivateks tokenite nimedeks. Kasuta background-primary, foreground-secondary või border-muted, mitte pesastatud võtmeid nagu background.primary või foreground.secondary. Iga väljastatud tokeni nimi peab vastama mustrile ^[a-zA-Z0-9][a-zA-Z0-9-]*$; lükka tagasi ja kirjuta ümber iga võti, mis selle testi ei läbiks.

Normaliseeri URL-i frontmatter enne mis tahes Markdowni kirjutamist. Järjekord on: kogu tõendid, vali ekspordisiht, kaardista tõendid kanoonilisse skeemi, lükka tagasi vigased kujud ja seejärel kirjuta dokument. Ära kunagi koosta kõigepealt proosat ja kohanda YAML-i hiljem.

URL-i frontmatter peab vastama järgmistele kujureeglitele:

• colors on kehtivate tokenite nimede ja väärtuste lame kaart.
• typography on nimetatud skaalade kaart; iga skaala on kaart, mis kasutab ainult kanoonilisi välju.
• rounded ja spacing on kehtivate tokenite nimede ja väärtuste lamedad kaardid.
• components võib viidata kanoonilistele tokeniteedele, kuid ei tohi tuua sisse teist tokeniskeemi.

Kui normaliseerimine nõuaks tokeni nime, välja, skaala või semantilise seose leiutamist, jäta kandidaat välja.

Väljaspool ülevaadet peab iga Markdowni lause muutma mõnd teostusvalikut. Kustuta komponentide inventuurid, üldised disainisoovitused ja proosa, mis ainult kordab YAML-i.

Säilita iga reegli ulatus ja suund. Kui teostus on vastuolus selgesõnalise juhisega, dokumenteeri juhis ja teata vastuolust väljaspool faili DESIGN.md.

4. Kirjuta dokument

Alusta väikseima kehtiva frontmatteriga:

---
version: alpha
name: <string>
description: <string>
---

Kohustuslik on ainult name. Lisa colors, typography, rounded, spacing või components ainult siis, kui juhtiv allikas juba määratleb selle nimetatud süsteemi või lepingu. Ära loo tokenite nimesid teostusväärtuste korrastamiseks. Tokeniviited kasutavad kuju {path.to.token}.

Kasuta skeemikujulisi kaarte, mitte kopeeritud allika pesastust. Tüpograafiaskaala on alati nimetatud ja selle omadused on kaardistatud selle alla:

typography:
  sans:
    fontFamily: Geist
  mono:
    fontFamily: Geist Mono

Kui allikas määratleb ainult --radius, kirjuta rounded.base, mitte rounded.radius; ära tuleta sm, md, lg ega xl utiliitklassidest või korduvatest väärtustest. Enne salvestamist uuri parsitud frontmatterit ja lükka see ise tagasi, kui mõni typography alamelement on skalaarne või kui rounded sisaldab võtmeid, mida juhtivas allikas pole.

Alusta jaotisega ## Overview. Kirjelda ainult toote eesmärki ja tõenditega toetatud disainisuunda. Ära tee kokkuvõtet lehtedest, komponentidest, tokenitest ega teostusest. Lisa ainult toetatud jaotisi selles järjekorras:

1. Colors
2. Themes
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

Ära loo jaotist ainult seetõttu, et see vormingus olemas on. Ära muuda kaasatud jaotiste järjekorda ega dubleeri neid. Lisa tundmatu jaotis ainult siis, kui toetatud juhis ei mahu ühtegi standardjaotisse.

Markdown talletab disainikavatsuse ja rakendusjuhised. Välja arvatud varulahendusena kasutatav tabel ## Themes, ära pane Markdowni tokenite inventuure, komponentide konfiguratsiooni, lähtesüntaksit ega dokumenteerimismetoodikat.

Lisa keeld (Don't) ainult siis, kui juhtiv allikas sõnastab selgesõnalise keelu.

• Pane täpsed normatiivsed väärtused YAML-frontmatterisse, välja arvatud alternatiivsete teemade väärtused, kui paigaldatud spetsifikatsioon ei suuda režiime esitada.
• Pane toetatud põhjendused ja rakendusjuhised Markdowni.
• Säilita olemasoleva DESIGN.md heakskiidetud otsused, kui kasutaja või kehtivad juhtivad tõendid neid ei asenda.
• Ära leiuta brändi isikupära, sihtrühma ega emotsionaalset põhjendust.
• Ära lisa faili DESIGN.md viiteid, auditimärkmeid, tagasilükatud kandidaate, vastuolusid ega lahendamata küsimusi.

Enne salvestamist kustuta:

• iga YAML-token, mida juhtiv allikas pole juba nimetanud
• iga lehepõhine käitumine, mis on esitatud kogu toodet hõlmava reeglina
• iga teostusmuster, mis on vastuolus selgesõnalise juhisega
• iga keeld, mida pole selgesõnaliselt sõnastatud
• iga täpne teostusväärtus väljaspool YAML-frontmatterit või varulahenduse tabelit ## Themes
• iga komponendikonfiguratsioon või dokumenteerimismetoodika Markdownis
• iga lause, mis ei muuda tulemuseks olevat DESIGN.md-d

Tee üks viimane tühikäigu läbimine: eemalda ebamäärased soovitused nagu „ole põhjalik“, „hoia see viimistletud“ või „kasuta tervet mõistust“. Jäta alles ainult tõendiväravad, skeemipiirangud või rakendusreeglid, mis dokumenti muudavad.

5. Valideeri

Käivita struktuurne lintimine:

npx @google/design.md lint DESIGN.md

Seejärel käivita üks ühilduvuseksport eespool valitud sihiga:

npx @google/design.md export --format <format> DESIGN.md

Uuri väljundit. Iga täidetud frontmatteri kategooria, mida siht toetab, peab väljastama vastava tokenikategooria; tühi või puuduv kategooria on skeemiviga ka siis, kui käsk lõpeb edukalt. Kirjuta frontmatter ümber ja käivita valideerimine uuesti, kuni kategooria väljastatakse, välja arvatud juhul, kui siht tõesti ei suuda seda esitada. Ära teata edust, kui mõni täidetud kategooria ekspordist puudub. Ära tagasta dokumenti, kui lint või eksport ebaõnnestub. Ära eemalda toetatud disainiteavet ainult eksportija piirangu rahuldamiseks; teata selle asemel piirangust. Ära loo ega säilita eksporditud faile.

css-tailwind puhul kontrolli järgmisi väljundiperesid: colors → --color-*, typography.<name>.fontFamily → --font-*, typography.<name>.fontSize → --text-*, rounded → --radius-* ja spacing → --spacing-*. Tüpograafiakirjed on nimetatud skaalad; pane fontFamily, fontSize ja lineHeight iga skaala sisse, mitte kunagi suvalise lähtepesastuse alla nagu font-family. Kui typography on täidetud, kuid eksport ei sisalda ei --font-* ega --text-*, on dokument kehtetu ja tuleb enne teatamist ümber kirjutada.

Olemasoleva dokumendi uuendamisel säilita ajutiselt selle algne sisu ja käivita:

npx @google/design.md diff <previous-file> DESIGN.md

Taasta iga eemaldatud heakskiidetud otsus, kui kehtivad juhtivad tõendid või kasutaja seda selgesõnaliselt ei asenda.

6. Aruanne

Tagasta:

• režiim ja auditeeritud toode või URL
• loodud või uuendatud DESIGN.md
• kasutatud juhtivad allikad
• vastuolud või toetuseta valdkonnad, mis dokumendist välja jäeti
• lõplikud lint- ja ekspordi tulemused

URL-režiimis märgi väljund rekonstrueeritud mustandiks.