Начало работы с Lily

Установка

Lily публикуется в виде отдельных Git-репозиториев для каждого фреймворка. Быстрее всего попробовать её, клонировав headless-репозиторий вашего стека:

git clone https://github.com/LilyDesignSystem/lily-design-system-react-headless
cd 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

Headless-библиотеки рассчитаны на клонирование или включение в проект: считайте исходный код источником истины и копируйте нужное. Помощники настроек дополнительно поставляются как устанавливаемые пакеты с конвейером сборки и публикации (npm для JS-фреймворков, NuGet для Blazor).

Использование headless-компонента

Headless-компоненты поставляются с семантическим HTML, ARIA и свойствами, но без CSS. Вот кнопка в каждом фреймворке:

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-svelte-sveltekit-examples
cd 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 поставляется с 45 самостоятельными эталонными темами в каталоге themes/. Каждая — одна таблица стилей, нацеленная на классы-зацепки Lily: подключите её — и оформление готово:

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

В набор входят:

• Государственный сектор — NHS England, NHS Scotland и NHS Wales (варианты для пациентов и для специалистов), GOV.UK GDS и Веб-дизайн-система США.
• По мотивам продуктов компаний — Adobe Spectrum, Mozilla Protocol.
• Универсальные — светлая, тёмная, nord, dracula, wireframe и ещё три десятка.

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

Помощники настроек

У каждого фреймворка есть сопутствующий каталог *-helpers с восемью небольшими «пикерами» (и picker-bar, который их объединяет). Каждый — это headless-кнопка с иконкой, открывающая всплывающее окно — список вариантов, список ссылок, форму поиска или (для date-time-picker) диалог выбора даты, — а не нативный <select>; безопасен для SSR и поставляется без CSS:

• theme-picker — загружает таблицы стилей тем во время выполнения, подменяя управляемый <link>, задаёт data-theme у документа и при желании сохраняет выбор в localStorage.
• locale-picker — задаёт lang и dir (с автоматическим определением письма справа налево), чтобы ваша библиотека 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-svelte-helpers

Каталог Svelte — каноническая основа; порты для React, Vue, Angular, HTML, Nunjucks, Web Components и Blazor соответствуют ему контракт в контракт. См. учебник по помощникам.

Доступность

Компоненты нацелены на WCAG 2.2 AAA. Они следуют таким паттернам:

• Семантические HTML-элементы вместо универсальных <div>.
• <label for="id">, связывающий подписи с полями ввода.
• aria-labelledby / aria-describedby для перекрёстных ссылок.
• aria-invalid + aria-errormessage для состояний ошибки.
• role="alert" и aria-live для динамического содержимого.
• aria-pressed, aria-expanded, aria-current для состояния.
• Перемещаемый 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 (через плагин Vite от Analog).
• Nunjucks: Vitest с вспомогательной функцией отрисовки.
• Blazor: bUnit.

Тесты используют только встроенные матчеры Vitest — никогда матчеры jest-dom. Это делает наборы тестов переносимыми. Примеры приложений добавляют сквозные наборы Playwright, базовые уровни доступности axe-core и обход адаптивных размеров окна.

ИИ-агенты

Этот сайт публикует llms.txt и llms.json в корне — тщательно составленную карту самых важных страниц для любого инструмента, следующего соглашению llms.txt.

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

Устранение неполадок

Как внести вклад

Lily молода и рада сотрудничеству. Сейчас наиболее полезны такие вклады:

• Новые компоненты (особенно паттерны из зарекомендовавших себя дизайн-систем).
• Новые темы — каждая представляет собой отдельную таблицу стилей, отлично очерченный первый запрос на слияние.
• Более удачное оформление примеров — покажите, что возможно.
• Переводы строк примеров приложений.
• Отчёты об ошибках с минимальным воспроизведением.
• Аудиты доступности со скринридерами и вспомогательными технологиями.

Открывайте обращения и запросы на слияние в нужном репозитории на github.com/LilyDesignSystem.

Сообщество и поддержка

• Вопросы и отчёты об ошибках — откройте обращение в нужном репозитории на github.com/LilyDesignSystem.
• Электронная почта — сопровождающий читает joel@joelparkerhenderson.com и рад сотрудничеству, советам и отзывам.
• Зеркала — Lily также публикуется на Codeberg и GitLab, так что вы можете участвовать с той платформы, которая вам удобнее.
• Поведение — проект следует стандартному кодексу поведения; будьте добры и исходите из добросовестности.

Частые вопросы