شروع کار با 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 ۵۷ پوستهٔ مرجع مستقل را در پوشهٔ 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 — برگهٔ اشتراک‌گذاری بومی یا فهرست مقصدهای ارائه‌شده توسط مصرف‌کننده را باز می‌کند، به‌علاوهٔ رونوشت نشانی. مالک یک کنش است، نه یک ترجیح: چیزی اعمال نمی‌کند، چیزی ذخیره نمی‌کند.
• 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 برای حالت.
• تب‌ایندکس سیار tabindex برای جدول‌های شبکه‌ای.

نشانگرهای تمرکز عمداً توسط مصرف‌کننده تأمین می‌شوند — Lily هرگز حلقهٔ تمرکز پیش‌فرضی نمی‌کشد که با طراحی شما تعارض داشته باشد. برنامه‌های نمونه خط پایهٔ axe-core پاکی را در همهٔ مسیرهایشان حفظ می‌کنند.

بین‌المللی‌سازی

هر برچسب، جای‌نگهدار، پیام خطا و متن دکمه یک ویژگی است. رشتهٔ ثابت‌نوشته‌ای وجود ندارد. چارچوب ترجمهٔ دلخواهتان را وصل کنید — Paraglide، i18next، vue-i18n، react-intl، فایل‌های .resx، هر چیزی.

برای تاریخ‌ها، اعداد و ارزها، مؤلفه‌ها رشته‌های از پیش قالب‌بندی‌شده می‌پذیرند: شما با Intl.DateTimeFormat / Intl.NumberFormat / کتابخانهٔ دلخواهتان قالب‌بندی می‌کنید و نتیجه را می‌دهید.

یاریگر locale-picker با تنظیم lang و dir روی ریشهٔ سند، محلی انتخاب‌شده را به کتابخانهٔ i18n شما اعلام می‌کند.

آزمون

هر زیرپروژهٔ چارچوب آزمون‌های خودش را با پشتهٔ مرسوم خود عرضه می‌کند:

• 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 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 فرستاده می‌شود، تا بتوانید از فورجی که ترجیح می‌دهید مشارکت کنید.
• رفتار — پروژه از یک آیین‌نامهٔ رفتاری استاندارد پیروی می‌کند؛ مهربان باشید، حسن نیت را فرض کنید.

پرسش‌های متداول