Pro vývojáře

Gov Design System CE je postavený na standardních webových API a Web Components. Díky tomu se dá použít v jakémkoli frameworku i bez frameworku. Pro React, Angular a Vue navíc existují oficiální obalové balíčky (wrappery).

Ukázkové projekty (skeletony) ​

Nejrychlejší cesta je začít od funkčního projektu. Pro každé prostředí existuje minimální skeleton — jedna stránka, několik komponent, žádný kód, který byste museli mazat.

Skeletony jsou součástí repozitáře design systému v adresáři starters/.

Požadavky ​

Node.js 22 nebo novější (v každém skeletonu je .nvmrc). Skeleton pro Angular vyžaduje Node.js 22.22.3 nebo novější — tuto hranici si vynucuje Angular CLI.

Příkazy ​

Všechny skeletony mají stejná tři npm skripta:

npm install     # instalace závislostí
npm run dev     # vývojový server s hot reloadem
npm run build   # produkční build do adresáře dist/
npm run preview # zobrazení produkčního buildu

Co konkrétně dělají, se mezi prostředími liší:

Několik věcí, které je dobré vědět předem:

• npm run build zahrnuje kontrolu typů. Pokud build spadne na chybě typu, nejde o chybu bundleru — projděte hlášení z tsc, vue-tsc, respektive z Angular kompilátoru. Právě proto je typová kontrola součástí buildu: chyby v použití komponent se tak objeví při buildu, ne až v prohlížeči.
• Port pro Angular je 4200, ne 527x. Jde o výchozí hodnotu Angular CLI, kterou skeleton záměrně nemění, protože je to hodnota, kterou vývojáři v Angularu očekávají. Zbylé tři skeletony mají porty nastavené v vite.config.ts tak, aby šly spustit vedle sebe.
• npm run preview u Angularu funguje jinak. U Vanilla, Reactu a Vue spustí vite preview, tedy statický server nad hotovým buildem z dist/. Angular obdobný příkaz nemá, takže npm run preview tam spouští ng serve --configuration production — vývojový server v produkční konfiguraci. Je to blízko produkčnímu chování, ale není to totéž jako naservírovat hotový build. Pokud chcete opravdu ověřit výstup buildu, naservírujte dist/angular/browser/ jakýmkoli statickým serverem.
• Nasazení je u všech čtyř statické — obsah adresáře s buildem nakopírujte na webserver nebo do CDN. Skeletony nepotřebují Node.js runtime na serveru.

Co skeleton obsahuje ​

Jednu stránku s tlačítkem, kartou, formulářovým polem, ikonou a přepínačem světlého a tmavého režimu. To stačí na ověření, že jsou správně zapojené styly, design tokeny, fonty i ikony.

Není to skeleton aplikace — nenajdete v něm router, layout ani správu stavu. Tyhle věci jsou vaše rozhodnutí. Každý skeleton má vlastní README.md, kde je popsané, který soubor za co odpovídá.

Instalace ​

Základní balíčky potřebujete vždy:

npm install @gov-design-system-ce/components \
            @gov-design-system-ce/styles \
            @gov-design-system-ce/icons \
            @gov-design-system-ce/fonts

Pokud používáte framework, přidejte navíc odpovídající wrapper — viz návody níže.

Styly ​

Balíček @gov-design-system-ce/styles neobsahuje jeden soubor, ale několik samostatných bundlů. Který z nich potřebujete, závisí na tom, co z design systému používáte — a chybějící soubor se neprojeví žádnou chybou v konzoli, jen nenastylovaným výstupem.

Základ pro web-komponenty ​

Tuto pětici naimportujte vždy. Na pořadí záleží: tokens.css musí být první, protože ostatní soubory z něj čtou proměnné.

/* Proměnné (design tokeny). Vždy jako první. */
@import "@gov-design-system-ce/styles/tokens.css";
/* Základní nastavení. */
@import "@gov-design-system-ce/styles/styles.css";
/* Layout a kontejnery. */
@import "@gov-design-system-ce/styles/layout.css";
/* Styly jednotlivých komponent. */
@import "@gov-design-system-ce/styles/components.css";
/* Animace. */
@import "@gov-design-system-ce/styles/animations.css";

S touto pěticí jsou správně nastylované všechny web-komponenty (gov-button, gov-card, gov-form-*, gov-tabs, …) — tedy to, co obsahují skeletony a co je popsané v sekci Komponenty.

Kdy potřebujete další soubory ​

@import "@gov-design-system-ce/styles/templates.css";

Import po jednotlivých komponentách ​

Kromě bundlů balíček exportuje i styly jednotlivých komponent a šablon — pro projekt, který používá jen několik komponent, je to menší CSS než celé components.css:

@import "@gov-design-system-ce/styles/components/gov-button.css";
@import "@gov-design-system-ce/styles/templates/gov-footer.css";

tokens.css, styles.css a layout.css jsou potřeba i v tomto případě. Názvy odpovídají komponentám a šablonám — úplný seznam je v poli exports v package.json balíčku @gov-design-system-ce/styles.

Ikony ​

Ikony z balíčku @gov-design-system-ce/icons je nutné zkopírovat do veřejného adresáře vašeho projektu. Nejsou součástí JS bundlu — komponenta gov-icon si je stahuje za běhu.

Struktura adresářů je podstatná ​

Komponenta gov-icon stahuje ikonu z adresy:

${iconsPath}/${type}/${name}.svg

Atribut type odpovídá názvu podadresáře v balíčku a jeho výchozí hodnota je components. Zápis <gov-icon name="chevron-right"></gov-icon> tedy vede na požadavek na /assets/icons/components/chevron-right.svg.

Příklad s balíčkem copyfiles — všimněte si, že každý podadresář má vlastní cíl:

npm install copyfiles --save-dev

{
  "scripts": {
    "copy:icons": "copyfiles -f \"./node_modules/@gov-design-system-ce/icons/lib/components/*\" public/assets/icons/components && copyfiles -f \"./node_modules/@gov-design-system-ce/icons/lib/complex/*\" public/assets/icons/complex && copyfiles -f \"./node_modules/@gov-design-system-ce/icons/lib/colored/*\" public/assets/icons/colored"
  }
}

Ve skeletonech pro Vanilla, React a Vue je stejná věc vyřešená přes vite-plugin-static-copy, v Angularu přes pole assets v angular.json.

Sady ikon ​

Přehled dostupných názvů najdete na stránce Ikony.

Fonty ​

Balíček @gov-design-system-ce/fonts obsahuje soubory .woff2 a k nim SCSS partial. Zkopírujte soubory fontů do veřejného adresáře a partial naimportujte:

{
  "scripts": {
    "copy:fonts": "copyfiles -f \"./node_modules/@gov-design-system-ce/fonts/lib/*.woff2\" public/assets/fonts"
  }
}

/* Cesta musí odpovídat tomu, kam jste fonty zkopírovali. */
$gov-font-path: "/assets/fonts";
$version: "4.7.1";
@import "@gov-design-system-ce/fonts/lib/roboto";

Proměnná $gov-font-display umožňuje nastavit font-display (výchozí auto).

Konfigurace ​

Chování design systému se řídí objektem window.GOV_DS_CONFIG. Musí být nastavený dříve, než se zaregistrují komponenty — tedy před voláním defineCustomElements(), respektive před bootstrapem aplikace.

window.GOV_DS_CONFIG = {
    iconsPath: "/assets/icons",
    canValidateWcagOnRender: true,
}

Návody podle prostředí ​

Sloty ​

Většina komponent přijímá obsah přes sloty. Názvy slotů se neshodují s texty nadpisů — například gov-card má slot headline, nikoli title. Když uvedete neexistující název slotu, obsah se bez chyby vykreslí jako běžný obsah komponenty na špatném místě.

<gov-card>
    <h3 slot="headline">Nadpis karty</h3>
    <p>Obsah karty.</p>
    <gov-button slot="footer" type="outlined" color="primary" size="s">Více</gov-button>
</gov-card>

Dostupné sloty konkrétní komponenty najdete vždy na její stránce v sekci Komponenty.

V Reactu sloty nefungují — obsah se předává přes props. Mapování najdete v návodu Použití s Reactem.

Popisky formulářových prvků ​

Formulářová pole nemají vlastní atribut label. Popisek se skládá z gov-form-control a gov-form-label, které se spojují přes shodný identifier:

<gov-form-control>
    <gov-form-label identifier="jmeno">Jméno</gov-form-label>
    <gov-form-input identifier="jmeno" placeholder="Jan Novák"></gov-form-input>
</gov-form-control>

Podporované prohlížeče ​

• Edge — poslední 3 verze
• Chrome — poslední 10 verzí
• Firefox — poslední 10 verzí
• Safari — poslední 3 verze
• iOS — poslední 3 verze
• Android — verze 6 a novější