Първи стъпки с 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 (чрез приставката Vite на Analog).
• Nunjucks: Vitest с помощник за изобразяване.
• Blazor: bUnit.

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

AI агенти

Този сайт публикува 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, за да можете да участвате от форджа, който предпочитате.
• Поведение — проектът следва стандартен кодекс за поведение; бъдете любезни, предполагайте добра воля.

Често задавани въпроси