Első lépések a Lilyvel

Telepítés

A Lily egyetlen Git-monorepóban él, minden keretrendszer fej nélküli könyvtárának, segédcsomagjainak és példaalkalmazásának külön könyvtárával. A leggyorsabb kipróbálás: klónozd a monorepót, és nyisd meg a fej nélküli könyvtárat a saját technológiai veremedhez:

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-react-headless
pnpm install

Ugyanez a minta működik a többi keretrendszerhez is:

• @lilydesignsystem/html-headless – nem kell telepíteni; másold a .html fájlokat
• @lilydesignsystem/svelte-headless — pnpm install
• @lilydesignsystem/react-headless — pnpm install
• @lilydesignsystem/vue-headless — pnpm install
• @lilydesignsystem/angular-headless — pnpm install
• @lilydesignsystem/nunjucks-headless — pnpm install
• lily-design-system-blazor-headless — dotnet build

A fej nélküli könyvtárakat klónozásra vagy beemelésre tervezték – tekintsd a forráskódot az igazság forrásának, és másold, amire szükséged van. beállítássegédek ezenfelül telepíthető csomagokként is kaphatók build- és kiadási csővezetékkel (npm a JS-keretrendszerekhez, NuGet a Blazorhoz).

Fej nélküli komponens használata

A fej nélküli komponensek szemantikus HTML-t, ARIA-t és tulajdonságokat adnak – de CSS-t nem. Íme egy Button minden keretrendszerben:

HTML

<button class="button" type="button" aria-label="Save">
  Save
</button>

Svelte

<script>
  import Button from "lily-design-system-svelte-headless/components/Button/Button.svelte";
</script>

<Button onclick={save}>Save</Button>

React

import Button from "lily-design-system-react-headless/components/Button";

<Button onClick={save}>Save</Button>

Vue

<script setup>
  import Button from "lily-design-system-vue-headless/components/Button.vue";
</script>

<Button @click="save">Save</Button>

Angular

import { Button } from "@lilydesignsystem/angular-headless";

@Component({
  imports: [Button],
  template: `<lily-button (click)="save()">Save</lily-button>`,
})

Blazor

<Button OnClick="Save">Save</Button>

Nunjucks

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "button" }) }}

Stílusozott példa használata

A példaalkalmazások CSS-t, útvonalakat és teljes demóoldalakat tartalmaznak. A legjobb kísérletezési mód a SvelteKit-, Next-, Nuxt-, Analog- vagy Eleventy-példaalkalmazás elindítása, és a demó megtekintése itt: /components.

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-sveltekit-examples
pnpm install
pnpm run dev

Utána nyisd meg a http://localhost:5173 címet, és böngéssz itt: /components.

Stílusozás és tervezési tokenek

Minden komponens egyetlen kebab-case osztállyal renderelődik a gyökérelemén. Például a <Button> így renderelődik: <button class="button">. Stílusozd úgy, ahogy akarod:

.button {
  background: var(--my-primary);
  color: #fff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
}
.button:hover { background: var(--my-primary-hover); }

A Lily alapértelmezett színpalettája (a példaalkalmazásokban használt):

• Elsődleges: #2563eb
• Veszély: #dc2626
• Figyelmeztetés: #f59e0b
• Siker: #16a34a
• Oldalháttér: #f9fafb
• Kártyaháttér: #ffffff

Ezek javaslatok, nem követelmények. Cseréld le őket a saját márkapalettádra, és a Lily örömmel követi.

Kész témák

Nem akarsz CSS-t írni a nulláról? A Lily 57 önálló referenciatémát szállít a themes/ könyvtárban. Mindegyik egy-egy stíluslap, amely a Lily osztályhorgait célozza – linkeld be, és már stílusozott vagy:

<link rel="stylesheet" href="/assets/themes/united-kingdom-government-digital-service.css" />

A készlet a következőket fedi le:

• Közszféra – NHS England, NHS Scotland és NHS Wales (mindegyik betegeknek és szakembereknek szóló változatban), GOV.UK GDS és a U.S. Web Design System.
• Szállítók által ihletett – Adobe Spectrum, Mozilla Protocol.
• Általános célú – light, dark, nord, dracula, wireframe és még vagy harminc.

A témaválasztók a :where(...)-t használják, így a saját CSS-ed mindig nyer a specificitásban. Párosítsd őket az alábbi theme-picker segéddel a futásidejű váltáshoz, vagy kövesd a témázási oktatóanyagot.

Beállítássegédek

Minden keretrendszernek nyolc kis választója van, mindegyik saját lily-design-system-{framework}-{package} csomag (és egy picker-bar , amely összeállítja őket). Mindegyik egy fej nélküli ikongomb, amely előugró ablakot nyit – listadobozt, linklistát, keresőűrlapot vagy (a date-time-picker esetében) dátumválasztó párbeszédpanelt –, nem natív <select>; SSR-biztos; és nem szállít CSS-t:

• theme-picker – futásidőben tölti be a témák stíluslapjait egy kezelt <link>cseréjével, beállítja a data-theme attribútumot a dokumentumon, és igény szerint tartósan elmenti ide: localStorage.
• locale-picker – beállítja a lang és a dir attribútumot (automatikus RTL-érzékeléssel), hogy az i18n-könyvtárad követhesse; maga nem fordít semmit.
• text-size-picker – beállítja a data-text-size attribútumot a dokumentumon; a CSS-ed rendeli hozzá az egyes értékekhez a betűméretet.
• motion-picker – beállítja a data-motion attribútumot a dokumentumon, a látogató csökkentett mozgás beállításából kiindulva; a CSS-ed és a szkriptjeid döntik el, mit kell elnyomni.
• search-picker – egy ikongomb, amely keresőmezőt nyit; a beküldés egy keresőoldalra navigál. Egy műveletet birtokol, nem beállítást.
• link-picker – egy otthon ikon, amely megnyitja az alkalmazásod által meghatározott oldallinkek menüjét (Kezdőlap, Rólunk, Kapcsolat, Adatvédelmi irányelvek, …). Egy műveletet birtokol, nem beállítást.
• share-picker – megnyitja a natív megosztási lapot vagy a fogyasztó által megadott célok listáját, plusz az URL másolását. Egy műveletet birtokol, nem beállítást: semmit nem alkalmaz, semmit nem ment.
• date-time-picker – egy szövegmező plusz egy APG-dátumválasztó párbeszédpanel dátumhoz, időhöz vagy mindkettőhöz. Egy űrlapértéket birtokol, nem beállítást: az ISO-karakterlánc oda-vissza alakítható ide: <input type="date">.

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker

A Svelte-katalógus a kanonikus referencia; a React-, Vue-, Angular-, HTML-, Nunjucks-, Web Components- és Blazor-portok szerződésről szerződésre megfelelnek neki. Lásd a segédek oktatóanyagát.

Hozzáférhetőség

A komponensek célja a WCAG 2.2 AAAszint. Ezeket a mintákat követik:

• Szemantikus HTML-elemek az általános <div>s.
• <label for="id"> -ek helyett, amelyek a címkéket a bemenetekhez kötik.
• aria-labelledby / aria-describedby a kereszthivatkozásokhoz.
• aria-invalid + aria-errormessage a hibaállapotokhoz.
• role="alert" és aria-live a dinamikus tartalomhoz.
• aria-pressed, aria-expanded, aria-current az állapothoz.
• Roving tabindex a rácsokhoz.

A fókuszjelzőket szándékosan a fogyasztó adja – a Lily soha nem rajzol olyan alapértelmezett fókuszgyűrűt, amely ütközne a terveddel. A példaalkalmazások tiszta axe-core alapvonalat tartanak az összes útvonalukon.

Nemzetköziesítés

Minden címke, helyőrző, hibaüzenet és gombfelirat tulajdonság. Nincsenek beégetett karakterláncok. Kapcsold be a választott fordítási keretrendszert – Paraglide, i18next, vue-i18n, react-intl, .resx-fájlok, bármi.

Dátumokhoz, számokhoz és pénznemekhez a komponensek előre formázott karakterláncokat fogadnak: te formázol a Intl.DateTimeFormat / Intl.NumberFormat / a kedvenc könyvtáraddal, és átadod az eredményt.

A locale-picker segéd a kiválasztott nyelvi beállítást jelzi az i18n-könyvtáradnak a lang és a dir beállításával a dokumentum gyökerén.

Tesztelés

Minden keretrendszer-alprojekt saját, a keretrendszerre jellemző technológiai veremmel készült teszteket szállít:

• HTML: valódi böngészőket futtató WebDriverIO.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (az Analog Vite-bővítményén keresztül).
• Nunjucks: Vitest renderelő segéddel.
• Blazor: bUnit.

A tesztek csak a Vitest beépített illesztőit használják – soha nem a jest-dom -illesztőket. Ez hordozhatóvá teszi a tesztcsomagokat. A példaalkalmazások Playwright végpontok közötti csomagokat, axe-core hozzáférhetőségi alapvonalakat és reszponzív nézetablak-átvizsgálást adnak hozzá.

MI-ügynökök

Ez a webhely a gyökerében közzéteszi a llms.txt és a llms.json fájlt – a legfontosabb oldalainak gondozott térképét, minden olyan eszköznek, amely követi az llms.txt konvenciót.

A kanonikus monorepo ezenfelül két Claude Skills: lily-design-system-skill-t szállít: egy általános célú készséget, amely a Lily fogalmait, terminológiáját és összeállítási mintáit fedi le mindenkinek, aki a rendszerrel épít, és lily-design-system-maintainer-skill-t, egy műszaki készséget, amely a monorepo kötelező fájlszerkezetét és eszközeit fedi le mindenkinek, aki rajta dolgozik. Mindkettő a kanonikus monorepo gyökerében.

Hibaelhárítás

Közreműködés

A Lily fiatal, és szívesen fogadja az együttműködést. A jelenleg leghasznosabb hozzájárulások:

• Új komponensek (különösen bevált tervezési rendszerek mintái).
• Új témák – mindegyik egy önálló stíluslap, jól körülhatárolt első PR.
• Jobb példastílusozás – mutasd meg, mi lehetséges.
• A példaalkalmazás karakterláncainak fordításai.
• Hibajelentések minimális reprodukcióval.
• Hozzáférhetőségi auditok képernyőolvasókkal és kisegítő technológiákkal.

Nyiss issue-kat és PR-eket itt: github.com/LilyDesignSystem/lily-design-system.

Közösség és támogatás

• Kérdések és hibajelentések – nyiss egy issue-t itt: github.com/LilyDesignSystem/lily-design-system.
• E-mail – a karbantartó olvassa a joel@joelparkerhenderson.com címet, és szívesen fogadja az együttműködést, az útmutatást és a visszajelzést.
• Tükrök – a Lily ide is fel van töltve: Codeberg és GitLab, hogy az általad preferált forge-ról is részt vehess.
• Magatartás – a projekt egy szokásos magatartási kódexet követ; légy kedves, feltételezz jóhiszeműséget.

GYIK