Pierwsze kroki z Lily

Instalacja

Lily mieszka w jednym monorepozytorium Git, z katalogiem dla bezgłowej biblioteki, pakietów pomocniczych i aplikacji przykładowej każdego frameworka. Najszybszy sposób na wypróbowanie to sklonowanie monorepozytorium i otwarcie bezgłowej biblioteki dla twojego stosu:

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

Ten sam wzorzec działa dla pozostałych frameworków:

• @lilydesignsystem/html-headless — instalacja niepotrzebna; skopiuj pliki .html
• @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

Biblioteki bezgłowe są zaprojektowane do klonowania lub włączania do projektu — traktuj kod źródłowy jako źródło prawdy i kopiuj to, czego potrzebujesz. pomocnicy preferencji są dodatkowo dostarczani jako instalowalne pakiety z potokiem budowania i publikacji (npm dla frameworków JS, NuGet dla Blazor).

Użycie komponentu bezgłowego

Komponenty bezgłowe dostarczają semantyczny HTML, ARIA i właściwości — ale nie CSS. Oto Button w każdym frameworku:

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" }) }}

Użycie ostylowanego przykładu

Aplikacje przykładowe zawierają CSS, trasy i pełne strony demonstracyjne. Najszybszy sposób na eksperymentowanie to uruchomienie aplikacji przykładowej SvelteKit, Next, Nuxt, Analog lub Eleventy i obejrzenie dema pod adresem /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

Następnie otwórz http://localhost:5173 i przeglądaj /components.

Stylizacja i tokeny projektowe

Każdy komponent renderuje się z jedną klasą w kebab-case na swoim elemencie głównym. Na przykład <Button> renderuje się jako <button class="button">. Ostyluj go, jak chcesz:

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

Domyślna paleta kolorów Lily (używana w aplikacjach przykładowych) to:

• Główny: #2563eb
• Niebezpieczeństwo: #dc2626
• Ostrzeżenie: #f59e0b
• Powodzenie: #16a34a
• Tło strony: #f9fafb
• Tło karty: #ffffff

To sugestie, nie wymagania. Zastąp je paletą własnej marki, a Lily chętnie za nią podąży.

Gotowe motywy

Nie chcesz pisać CSS od zera? Lily dostarcza 57 samodzielnych motywów referencyjnych w katalogu themes/ . Każdy to jeden arkusz stylów celujący w haki klas Lily — podlinkuj go, a masz stylizację:

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

Zestaw obejmuje:

• Sektor publiczny — NHS England, NHS Scotland i NHS Wales (każdy w wariancie dla pacjentów i dla praktyków), GOV.UK GDS oraz U.S. Web Design System.
• Inspirowane dostawcami — Adobe Spectrum, Mozilla Protocol.
• Ogólnego przeznaczenia — light, dark, nord, dracula, wireframe i jeszcze około trzydziestu.

Selektory motywów używają :where(...), więc twój własny CSS zawsze wygrywa pod względem specyficzności. Połącz je z pomocnikiem theme-picker poniżej, aby przełączać w czasie działania, albo skorzystaj z samouczka o motywach.

Pomocnicy preferencji

Każdy framework ma osiem małych selektorów, każdy to osobny pakiet lily-design-system-{framework}-{package} (oraz picker-bar , który je składa). Każdy to bezgłowy przycisk z ikoną otwierający okienko — listę wyboru, listę linków, formularz wyszukiwania lub (w przypadku date-time-picker) okno wyboru daty — nie natywny <select>; jest bezpieczny dla SSR; i nie zawiera CSS:

• theme-picker — ładuje arkusze stylów motywów w czasie działania, podmieniając zarządzany <link>, ustawia data-theme w dokumencie i opcjonalnie zapisuje w localStorage.
• locale-picker — ustawia lang i dir (z automatycznym wykrywaniem RTL), aby twoja biblioteka i18n mogła za nimi podążać; sam niczego nie tłumaczy.
• text-size-picker — ustawia data-text-size w dokumencie; twój CSS mapuje każdą wartość na rozmiar czcionki.
• motion-picker — ustawia data-motion w dokumencie, wychodząc od ustawienia ograniczonego ruchu odwiedzającego; twój CSS i skrypty decydują, co wyciszyć.
• search-picker — przycisk z ikoną otwierający pole wyszukiwania; wysłanie przechodzi na stronę wyszukiwania. Odpowiada za akcję, nie za preferencję.
• link-picker — ikona domu otwierająca menu linków do stron definiowanych przez twoją aplikację (Strona główna, O nas, Kontakt, Polityka prywatności, …). Odpowiada za akcję, nie za preferencję.
• share-picker — otwiera natywny arkusz udostępniania lub listę miejsc docelowych dostarczoną przez konsumenta, plus kopiowanie adresu URL. Odpowiada za akcję, nie za preferencję: niczego nie stosuje, niczego nie zapisuje.
• date-time-picker — pole tekstowe plus okno wyboru daty zgodne z APG dla daty, godziny lub obu. Odpowiada za wartość formularza, nie za preferencję: ciąg ISO jest konwertowany tam i z powrotem do <input type="date">.

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

Katalog Svelte jest kanonicznym odniesieniem; porty dla React, Vue, Angular, HTML, Nunjucks, Web Components i Blazor odpowiadają mu kontrakt po kontrakcie. Zobacz samouczek o pomocnikach.

Dostępność

Komponenty celują w poziom WCAG 2.2 AAA. Stosują te wzorce:

• Semantyczne elementy HTML zamiast ogólnych <div>s.
• <label for="id"> łączące etykiety z polami.
• aria-labelledby / aria-describedby dla odwołań krzyżowych.
• aria-invalid + aria-errormessage dla stanów błędu.
• role="alert" i aria-live dla treści dynamicznych.
• aria-pressed, aria-expanded, aria-current dla stanu.
• Roving tabindex dla siatek.

Wskaźniki fokusu są celowo dostarczane przez konsumenta — Lily nigdy nie rysuje domyślnego pierścienia fokusu, który kolidowałby z twoim projektem. Aplikacje przykładowe utrzymują czystą bazę axe-core na wszystkich swoich trasach.

Internacjonalizacja

Każda etykieta, symbol zastępczy, komunikat o błędzie i tekst przycisku to właściwość. Nie ma ciągów wpisanych na sztywno. Podłącz wybrany framework tłumaczeń — Paraglide, i18next, vue-i18n, react-intl, pliki .resx, cokolwiek.

Dla dat, liczb i walut komponenty przyjmują sformatowane wcześniej ciągi: formatujesz za pomocą Intl.DateTimeFormat / Intl.NumberFormat / ulubionej biblioteki i przekazujesz wynik.

Pomocnik locale-picker sygnalizuje wybrane ustawienia regionalne twojej bibliotece i18n, ustawiając lang i dir w korzeniu dokumentu.

Testowanie

Każdy podprojekt frameworka dostarcza własne testy z użyciem jego typowego stosu:

• HTML: WebDriverIO uruchamiający prawdziwe przeglądarki.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (przez wtyczkę Analog Vite).
• Nunjucks: Vitest z pomocnikiem renderowania.
• Blazor: bUnit.

Testy używają wyłącznie wbudowanych matcherów Vitest — nigdy matcherów jest-dom . Dzięki temu zestawy testów są przenośne. Aplikacje przykładowe dodają zestawy end-to-end Playwright, bazy dostępności axe-core i przegląd responsywnych widoków.

Agenci AI

Ta witryna publikuje llms.txt i llms.json w swoim korzeniu — wyselekcjonowaną mapę najważniejszych stron, dla każdego narzędzia, które stosuje konwencję llms.txt.

Kanoniczne monorepozytorium dodatkowo dostarcza dwie Claude Skills: lily-design-system-skill: ogólnego przeznaczenia umiejętność obejmującą pojęcia, terminologię i wzorce kompozycji Lily dla każdego, kto buduje z użyciem systemu, oraz lily-design-system-maintainer-skill, techniczną umiejętność obejmującą układ wymaganych plików i narzędzia monorepozytorium dla każdego, kto przy nim pracuje. Obie leżą w korzeniu kanonicznego monorepozytorium.

Rozwiązywanie problemów

Współtworzenie

Lily jest młody i wita współpracę. Najbardziej przydatne wkłady w tej chwili to:

• Nowe komponenty (zwłaszcza wzorce z ugruntowanych systemów projektowych).
• Nowe motywy — każdy to jeden samodzielny arkusz stylów, dobrze ograniczony pierwszy PR.
• Lepsza stylizacja przykładów — pokaż, co jest możliwe.
• Tłumaczenia ciągów aplikacji przykładowych.
• Zgłoszenia błędów z minimalnym przykładem odtworzenia.
• Audyty dostępności z czytnikami ekranu i technologiami wspomagającymi.

Otwieraj zgłoszenia i PR-y na github.com/LilyDesignSystem/lily-design-system.

Społeczność i wsparcie

• Pytania i zgłoszenia błędów — otwórz zgłoszenie na github.com/LilyDesignSystem/lily-design-system.
• E-mail — opiekun czyta joel@joelparkerhenderson.com i wita współpracę, wskazówki i opinie.
• Kopie lustrzane — Lily jest również wysyłany do Codeberg i GitLab, abyś mógł uczestniczyć z forge, który wolisz.
• Zasady postępowania — projekt stosuje standardowy kodeks postępowania; bądź uprzejmy, zakładaj dobrą wiarę.

FAQ