البدء مع 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> أصليًا؛ وهو آمن للعرض على الخادم ولا يأتي بأي 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، فيمكنك المشاركة من المنصة التي تفضّلها.
• السلوك — يتبع المشروع مدونة سلوك معيارية؛ كن لطيفًا وافترض حسن النية.

الأسئلة الشائعة