Початок роботи з Lily

Встановлення

Lily живе в одному монорепозиторії Git з каталогом для «безголової» бібліотеки, пакетів допоміжних засобів і прикладу застосунку кожного фреймворку. Найшвидший спосіб спробувати — клонувати монорепозиторій і відкрити «безголову» бібліотеку для вашого стеку:

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

Той самий шаблон працює для інших фреймворків:

• @lilydesignsystem/html-headless — встановлення не потрібне; скопіюйте .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

«Безголові» бібліотеки створено для клонування чи вендорингу — вважайте вихідний код джерелом істини й копіюйте те, що потрібно. допоміжні засоби налаштувань додатково постачаються як встановлювані пакети з конвеєром збирання й публікації (npm для JS-фреймворків, NuGet для Blazor).

Використання «безголового» компонента

«Безголові» компоненти постачаються із семантичним HTML, ARIA та властивостями — але без CSS. Ось Button у кожному фреймворку:

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

Використання стилізованого прикладу

Приклади застосунків містять CSS, маршрути й повні демосторінки. Найшвидший спосіб поекспериментувати — запустити приклад застосунку SvelteKit, Next, Nuxt, Analog або Eleventy і переглянути демо за адресою /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

Потім відкрийте http://localhost:5173 і перегляньте /components.

Стилізація та дизайн-токени

Кожен компонент рендериться з одним класом kebab-case на кореневому елементі. Наприклад, <Button> рендерить <button class="button">. Стилізуйте його як завгодно:

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

Типова палітра кольорів Lily (використовується в прикладах застосунків):

• Основний: #2563eb
• Небезпека: #dc2626
• Попередження: #f59e0b
• Успіх: #16a34a
• Тло сторінки: #f9fafb
• Тло картки: #ffffff

Це пропозиції, а не вимоги. Замініть їх власною брендовою палітрою — і Lily охоче підлаштується.

Готові теми

Не хочете писати CSS з нуля? Lily постачається з 57 автономними еталонними темами в каталозі themes/ . Кожна — одна таблиця стилів, що націлена на клас-гачки Lily: підключіть її — і стилізація готова:

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

Набір охоплює:

• Публічний сектор — NHS England, NHS Scotland і NHS Wales (варіанти для пацієнтів і для практиків), GOV.UK GDS та U.S. Web Design System.
• За мотивами вендорів — Adobe Spectrum, Mozilla Protocol.
• Універсальні — light, dark, nord, dracula, wireframe та ще три десятки.

Селектори тем використовують :where(...), тож ваш власний CSS завжди виграє за специфічністю. Поєднайте їх із допоміжним засобом theme-picker нижче для перемикання під час виконання або дотримуйтеся посібник із тем.

Допоміжні засоби налаштувань

Кожен фреймворк має вісім невеликих засобів вибору, кожен у власному lily-design-system-{framework}-{package} пакеті (і picker-bar що їх збирає). Кожен — «безголова» кнопка-значок, що відкриває спливне вікно — список вибору, список посилань, форму пошуку або (для date-time-picker) діалог вибору дати — а не нативний <select>; безпечний для SSR; і постачається без CSS:

• theme-picker — завантажує таблиці стилів тем під час виконання, змінюючи кероване <link>, встановлює data-theme на документі та за потреби зберігає в localStorage.
• locale-picker — встановлює lang і dir (з автоматичним визначенням RTL), щоб ваша i18n-бібліотека могла за ним слідувати; сам нічого не перекладає.
• text-size-picker — встановлює data-text-size на документі; ваш CSS зіставляє кожне значення з розміром шрифту.
• motion-picker — встановлює data-motion на документі, починаючи з налаштування відвідувача щодо зменшеного руху; ваш CSS і скрипти вирішують, що вимкнути.
• search-picker — кнопка-значок, що відкриває поле пошуку; надсилання переходить на сторінку пошуку. Володіє дією, а не налаштуванням.
• link-picker — значок «додому», що відкриває меню посилань на сторінки, які визначає ваш застосунок (Головна, Про нас, Контакти, Політика конфіденційності, …). Володіє дією, а не налаштуванням.
• share-picker — відкриває нативне вікно поширення або список призначень від споживача, а також копіювання URL. Володіє дією, а не налаштуванням: нічого не застосовує, нічого не зберігає.
• date-time-picker — текстове поле плюс діалог вибору дати APG для дати, часу або обох. Володіє значенням форми, а не налаштуванням: рядок ISO проходить туди й назад до <input type="date">.

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

Каталог Svelte — канонічний еталон; порти React, Vue, Angular, HTML, Nunjucks, Web Components і Blazor відповідають йому контракт за контрактом. Див. посібник із допоміжних засобів.

Доступність

Компоненти орієнтовані на WCAG 2.2 AAA. Вони дотримуються таких шаблонів:

• Семантичні елементи HTML замість загальних <div>s.
• <label for="id"> що пов’язує мітки зі полями введення.
• aria-labelledby / aria-describedby для перехресних посилань.
• aria-invalid + aria-errormessage для станів помилок.
• role="alert" і aria-live для динамічного вмісту.
• aria-pressed, aria-expanded, aria-current для стану.
• Roving tabindex для сіток.

Індикатори фокуса навмисно надаються споживачем — Lily ніколи не малює типове кільце фокуса, що конфліктує з вашим дизайном. Приклади застосунків підтримують чисту базову лінію axe-core на всіх маршрутах.

Інтернаціоналізація

Кожна мітка, підказка в полі, повідомлення про помилку й текст кнопки — це властивість. Жорстко прописаних рядків немає. Підключіть обраний фреймворк перекладу — Paraglide, i18next, vue-i18n, react-intl, файли .resx, будь-що.

Для дат, чисел і валют компоненти приймають попередньо відформатовані рядки: ви форматуєте за допомогою Intl.DateTimeFormat / Intl.NumberFormat / улюбленої бібліотеки й передаєте результат.

Допоміжний засіб locale-picker повідомляє вашій i18n-бібліотеці про вибрану локаль, встановлюючи lang і dir на корені документа.

Тестування

Кожен підпроєкт фреймворку постачає власні тести з ідіоматичним стеком:

• HTML: WebDriverIO, що запускає справжні браузери.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (через плагін Analog Vite).
• Nunjucks: Vitest із допоміжним засобом рендерингу.
• Blazor: bUnit.

Тести використовують лише вбудовані матчери Vitest — ніколи jest-dom матчерів. Це зберігає набори тестів портативними. Приклади застосунків додають наскрізні набори Playwright, базові лінії доступності axe-core і перевірку в’юпортів.

ШІ-агенти

Цей сайт публікує llms.txt і llms.json у своєму корені — добірну карту найважливіших сторінок для будь-якого інструмента, що дотримується конвенції llms.txt.

Канонічний монорепозиторій також постачає два Claude Skills: lily-design-system-skill, універсальну навичку, що охоплює поняття, термінологію й шаблони композиції Lily для всіх, хто будує з її допомогою, та lily-design-system-maintainer-skill, технічну навичку, що охоплює обов’язкову структуру файлів і інструменти монорепозиторію для всіх, хто працює над ним. Обидві розташовані в корені канонічного монорепозиторію.

Усунення несправностей

Внесок

Lily молода й вітає співпрацю. Найкорисніші внески зараз:

• Нові компоненти (особливо шаблони з усталених дизайн-систем).
• Нові теми — кожна є однією автономною таблицею стилів, добре окреслений перший PR.
• Краща стилізація прикладів — покажіть, що можливо.
• Переклади рядків прикладів застосунків.
• Звіти про помилки з мінімальним відтворенням.
• Аудити доступності зі зчитувачами екрана та допоміжними технологіями.

Відкривайте issue та PR на github.com/LilyDesignSystem/lily-design-system.

Спільнота та підтримка

• Питання та звіти про помилки — відкрийте issue на github.com/LilyDesignSystem/lily-design-system.
• Ел. пошта — супровідник читає joel@joelparkerhenderson.com і вітає співпрацю, поради та відгуки.
• Дзеркала — Lily також публікується на Codeberg і GitLab, тож ви можете долучатися з улюбленої платформи.
• Поведінка — проєкт дотримується стандартного кодексу поведінки; будьте доброзичливими, припускайте добрі наміри.

Поширені запитання